Exploring Documentation Location Options

It's Not Just about Where but Also Sharable Current State

Introduction

In , I wrote about the high level concepts my team— Strategic Innovation Lab (SI Lab 🔍)—will reference/execute:

  • Problem Statements
  • Projects
  • Tasks

In , I wrote about the need for clarity on an Information Sharing Artifact (ISA 🔍) status. Who all has engaged with it, and what were some of those engagements.

I’ve worked through a conceptual workflow of information sharing, identified a few ISAs, and the inter-relation of those ISAs.

Now, I’ll explore some implementation options available to me, and review those. Some assumptions:

  1. Each person with a role in these processes should be able to access that documentation.
  2. There should exist a canonical location where all of us can reference.
  3. People should have space to develop their ideas and means for soliciting feedback and acceptance.
  4. The implementation ecosystem should already be used within Hesburgh Libraries 🔍.

Tools to Explore

At Hesburgh Libraries, we have access to several tools. The ones that I think of immediately are:

Jira

Jira focuses on managing the process flow of tasks and projects. This is a helpful view into the overall workflow status, but it’s not ideal for capturing the work execution activities of developing ISAs. What I mean by that is I can attach documents or link to Uniform Resource Locators (URLs 🔍) that are those documents. This would mean in adopting Jira, we’d need to establish a documentation organization strategy of the documents we link to.

Another way of thinking about this is; objects in Jira represent workflow state. Each object might point to some more robust and meaningful representation of that concept (e.g., the delivered documentation, the project charter, it’s ISA if you will). If you want to see a holistic perspective of the meaningful representations, Jira won’t be that tool.

As I see it, Jira could be a layer on-top of what I’m working to develop. But I suspect even then that it’s inadequate. After all, I should be able to look at a given ISA and see it’s state. If Jira’s the workflow management layer, it should reflect the current state of the underlying ISA, but there’s a synchronization issue that requires further development.

Given that we’re using a local instance of Jira 🔍, which runs contrary to our desired Cloud-first Initiative, I’m concerned that we may pivot from this tool. Much of what we use it for could be subsumed in Github’s projects and issue trackers. The primary concern of moving away from Jira would be the assessment of what’s in Jira that’s not in the underlying file system?

Google Drive

At Hesburgh Libraries we make heavy use of Google Drive 🔍. It provides a file system and excellent real-time collaboration features. However, it doesn’t provide much of any consideration for high level workflows.

Yes, you can propose changes to a document. But if you’re collectively working on a document, what does “publishing” it look like? What about publishing a group of documents together? If we adopt Google Drive, we’ll need to account for the concept of publication.

Proceeding with this path will require:

  1. Developing the file system structure.
  2. Developing some templates.
  3. Developing a workflow for moving ISAs to a published state.
  4. Developing a mechanism for exposing a Problem Statement dashboard and Project dashboard.

One aspect to consider is that all documents in the file system structure will be searchable in their current state by all participants. This could lead to cases where it’s unclear what is the agreed upon state of the totality of information.

That is to say, for one of my tasks, I’ve added a document to the Google Drive, but I’m currenting Drafting that document. No one has approved it. Yet a search of the Google Drive directory would turn up that task. Things get even trickier when I’m proposing changes to an already agreed upon ISA; my edits would be seen as proposed changes on the approved document.

To insulate against this potential confusion, we’d need to consider how to navigate this.

Github

I’m a developer, I’m comfortable and experienced with Github 🔍 and the workflow tools in the Github ecosystem. Github’s primary function is providing a web interface around versioning changes to a file system’s directory and it’s sub-directory.

Let’s assume we start with a directory and a main branch. The main branch will represent the agreed upon and published state of information. In the diagram, documents would be put in the main branch once someone took the Publishing action.

We could model an ISA workflow using branches and pull requests. The changes we propose via pull requests would be the ISAs we develop.

A major barrier that I see is advocating for a tool that is new to several people within the organization. In particular those responsible for the Reviewing and Commenting type actions. This would require understanding their concerns.

For now, however, I’m scoping this documentation locations to the activities of the SI Lab. Which limits the number of people impacted by this potential implementation. And we could work directly with them to understand and overcome the barriers new adopters encounter.

Proceeding with this path will require:

  1. Developing the file system structure.
  2. Developing some templates.
  3. Sketching out the expected Github workflow.
  4. Developing a mechanism for exposing a Problem Statement dashboard and Project dashboard.

One aspect that warrants an explicit call out: the main branch is visible by all participants. It reflects the current state of information. When I search this project on the main branch, I would only see the current state of information. Related to this feature is that individuals can develop proposed information changes without “polluting” the current information state.

Recommendation

Jira appears to be a workflow layer that loosely interacts with a file system. The file system provides the place for the ISAs and links between those ISAs. Jira can reference other issues, but that’s one level of indirection compared to me writing a decision document that references a project charter.

Given that my observed problem is around understanding the current state of documentation, I believe that adopting and developing a Github oriented solution makes sense. The fundamental activity of the pull request review ensures that there’s a process for “publishing” the deliverables.

Next up, let’s dive into a file system and some possible tooling.