Introduction
Previously, I wrote about Process Development and Documentation as a Deliverable. And I’ve been thinking even more about documention:
- Conceptual workflow for documentation
- Typology of documentation I generate
Before I dive into those, I want to add a term: Information Sharing Artifacts (ISA). An ISA is something I’ve taken the time to write and intend to share with someone. That someone could be my future self or another person. It’s intended to be somewhat durable so that once shared others could reshare it.
For much of my career, one of the most common ISAs I created was source code. These days, it’s a wide variety of things. I’ll get to that later.
First a Detour Into Coding
One of the joys I experience in writing software is that I address a perceived problem and put forward something that approximates a solution to that problem. I use “approximate” solution to highlight that I never know the full scope of the problem I’m trying to solve. Often times, I need to integrate that solution into a larger ecosystem of moving gears, each working towards other approximate solutions. It’s a bit like working on a puzzle.
The act of integration involves ensuring the code I introduce goes in the right places. In a small codebase, finding the right places is trivial. As the codebase grows, that becomes more difficult.
The challenge of organizing ten (10) things is different than one thousand (1,000) things which is different than ordering one hundred thousand (100,000) things.
I think of Sipity, an application that I developed and architected. Knowing that I was creating a collaborative, state-based todo application that would change as we better understood the workflow, I took the time to name the concepts and document them. Though, is there ever enough documentation? Or the write documentation in the moment?
One aspect that I don’t worry about is how to move code into the system, so that my code joins the grinding chaos of those gears.
The reason, every code base I work on has a known and mostly documented workflow. Some have more rigorous workflows than others, but almost all of them use branching and merging.
Let’s walk through that real quick:
From the current state of the code, I create a branch. This signifies “I’m starting work here.” That branch is where I develop and begin implementing my solution. It’s a bit like my own personal copy.
During the “coding” activity, I’m writing tests, “live” code, documentation, and creating meaningful commit messages to help future me understand why I did what I did.
When I’m ready to incorporate my solution into the system, I create a pull request. This is analogue to an author sending their document to an editor. Someone else, reviews the pull request and does one of three things:
- Leaves a comment
- Requests changes
- Approves the changes
During the pull request review cycle, I might offer up refinements to live code, tests, documentation, or even commit messages. Others might also add their own changes.
Eventually, assuming my implementation reasonably solves the stated problem, someone will approve the pull request and we’ll merge that change into the main line.
Coding Workflow Diagram
Below, the Conceptual Code Workflow Diagram visually describes the workflow I outlined above.
This diagram represents the state of working on the code, the actions to move to another state, and who takes them.
Below, you can reference the PlantUML 📖 text used to generate the diagram.
Plain Text Representation of the Conceptual Code Workflow Diagram
I wrote the following code block in the PlantUML syntax.
@startuml
[*] -> Developing : Implementor: Creates branch
Developing --> Reviewing : Implementor: Submits for review
Reviewing --> Developing : Reviewer: Requests changes
Reviewing --> Reviewing : Participant: Leaves commentary
Reviewing --> Merging : Reviewer: Accepts work
Merging --> [*] : Authorized Participant: Merges work into main
@enduml
This workflow process ensures that the current “operating” state of the main line is clear. It also provides clear points in the process where other people can consider the impact of a recommended change. And that recommended change is an atomic ISA.
Typology of Information Sharing Artifacts
In my work (and play), I generate a variety of ISAs:
- Blog Posts
- Software Solutions
- Meeting Agendas
- Meeting Minutes
- Project Charters
- Problem Statements
- Recommendations
- Decisions
- Architecture Diagrams
- Reports
- Procedures
- Presentations
In some cases the number of involved people is quite small; I’m the only one that decides when to publish a blog post. There are also artifacts in which the “state” is not overly important; I don’t fret too much about the state of a meeting’s agenda.
In the case of software solutions, the workflows are quite clear; because it’s only in the main line if it’s been deployed and is running in the main line. That is to say, it’s easy to look at the current working state and say “yup, I’ve added this specific gear to the machinery.”
However, in other cases, such as a Project Charter, the number of involved participants can be anathema to understanding it’s state. Have we agreed it’s complete? Are “we” the right people to assert it’s “completion”?
Think about an email, the more people on that email thread, the less likely you’ll get a response. The state of that email hangs like an unanswered call.
Conceptual Workflow for Documentation
As I’ve been thinking about and working on Process Development and Documentation as a Deliverable, I’ve looked at other non-code ISAs and observed missing processes.
For 23 years, I’ve worked in a collaborative software development environment. I’m well accustomed to hitting “publish” on code. However, I’ve rarely observed the same workflows for other ISAs.
So I started laying out a conceptual workflow. Below is a diagram of that workflow. The conceptual workflow for deploying ISAs is larger in scope than the above workflow, and in general the former entirely subsumes the latter.
Roles
In this conceptual experiment there are seven roles:
- Submitter
- Responder
- Responsible
- Accountable
- Consulted
- Informed
- Publisher
The actions that a role can take define the role. A person or group of people may have the role, and thus can take the action. I think it’s important to highlight that a person or group of people could fill these roles. In the case of a group, there would be an implied decision making framework for taking a state-changing action.
Some roles allow the assignment of other roles, others require external decisions (e.g., who has the Responder role?), and others are assigned by engaging the workflow (e.g., whoever submit’s the task gains the submitter role).
You may notice the presence of Responsible, Accountable, Consulted, and Informed. In this exercise, I’m drawing on the language of the Responsibility matrix assignment (RACI 📖); this is language that’s referenced in Hesburgh Libraries 📖 so I opted to repeat that language.
Information Sharing Artifact Workflow Diagram
Below, the Conceptual Information Sharing Artifact Workflow Diagram diagram visually describes deploying ISAs into the main line of operations.
This diagram represents the state of working on an ISAs, the actions to move to another state, and who takes them.
Below, you can reference the PlantUML text used to generate the diagram.
I can envision that the accountable role could add other responsible, consulted, and informed people through the life cycle of this workflow. Giving someone a role would likely be a non-state changinig action; which is something that Sipity accounts for.
Plain Text Representation of the Conceptual Information Sharing Artifact Workflow Diagram
I wrote the following code block in the PlantUML syntax. I have take some liberties to edit the output to be more legible. Most of that is removing \n characters.
@startuml
[*] --> Receiving : Submitter: Creates request
Receiving --> Assigning : Responder: routes to accountable
Assigning -> Assigning : Accountable: re-assigns (delegate? escalate?)
Assigning --> Drafting : Accountable: submits for drafting
Drafting --> Reviewing : Responsible: submits for Review
Reviewing -> Amending : Accountable: submits for Amendment
Amending --> Reviewing : Responsible: submits for Review
Reviewing -> Commenting : Accountable: submits for Comments
Commenting -> Commenting : Consulted: ask questions and offer comments
Commenting --> Refining : Accountable: submits for Modification
Refining --> Commenting : Accountable: re-submits for Comments
Commenting --> Publishing : Accountable: submits for Publication
Publishing --> [*] : Publisher: Adds request to Knowledge Base
Receiving : “Responder”
Receiving : assigns “Accountable”
Assigning : “Accountable”
Assigning : completes the “RACI”
Drafting : “Responsible”
Drafting : drafts the initial work
Reviewing : “Accountable”
Reviewing : reviews the work
Amending : “Responsible”
Amending : makes the suggested changes
Commenting : “Consulted”
Commenting : review and ask questions
Refining : “Accountable”
Refining : (and likely “Responsible”)
Refining : address questions
Publishing : “Publisher”
Publishing : takes the knowledge work
Publishing : and adds it to the
Publishing : Knowledge Base. (This
Publishing : could itself be significant
Publishing : work)
note left of Refining : “Accountable and Responsible: work on
refinements”
note “The process outlines moving proposals and documentation
from inception to publication. Throughout the process,
different roles may take different actions. None of this
precludes consultation.
Roles: Submitter, Responder, Responsible, Accountable,
Consulted, Informed, Publisher” as N1
note left of Publishing : “A general concession
is knowing where to put things requires
significant cognitive load. Hence This
task is separated from the drafting
and ratification process.”
@enduml
As I’ve worked through this diagram, at first it felt odd that there wasn’t activity nodes for collaboration (e.g., during the Drafting phase why aren’t the consulted roles somehow connected?) What I realized, and wasn’t immediately obvious, is that during the Drafting stage, I’m not describing what happens.
Instead, this conceptual diagram identifies who may push the ISA to a new phase of executing work on that ISA. In other words, if I’m assigned to draft a document, that doesn’t mean I can’t consult other people. Nor does it mean I can’t myself delegate that work to someone else. It simply means, when I’m the one that decides when I’m done drafting and ready to send it forward for review.
Conclusion
I’m working towards a proposal for an information sharing strategy. I’ve identified that incorporating software changes into the main line of operation is easy. I’ve also observed that deploying non-software ISAs into an organization is far more ad hoc and ambiguous compared to software.
Another way of thinking about it is, when I want to deploy non-software into an organization, I’m likely doing three things:
- Working on creating the ISAs.
- Making a decision on where to put them.
- Making lots of decisions on who to involve.
- Deciding when it’s done enough, and what that looks like.
And ultimately, never quite knowing “Have I written up an adequate solution approximation to the observed problem?”
And on the flip-side, when I encounter other people’s ISAs do I know that artifacts status? In software, if I see code in a branch but not the main line, I know that there’s a solution in active exploration.
But, when I see a project charter or decision document, do I know it’s status? Has it been decided? Is it open for discussion and feedback? Who can give feedback? And who can edit it outright?
Again, all of this is working at exploring an observed problem in my organization.