This post builds on Exploring Documentation Location Options. I’m working through how we can capture, share, and develop both our work products, our processes, and our administrative notes.
Top-Level Directories
I’ve built out a directory structure that reflects the Conceptual Relationship Diagram of the major Information Sharing Artifacts (ISAs 📖). This structure helps conceptualize the top level concepts; below are the top-level concepts and their purpose:
- README
- This document orients the reader to the top-level sub-directories. What to expect in those sub-directories.
- Administration
- The administrative documents of the team; in a way it's the things that don't fit the other sub-directories.
- Problem Statements
- The submitted problem statements and related documents.
- Processes
- The processes that our team uses to deliver projects and address problem statements.
- Projects
- The projects that we're working on. One project will relate to one or more problem statements.
Tree Representation of Directory Structure
I generated the following ASCII 📖 diagram using the tree command on a directory I created. This prototypes a possible structure.
An ASCII representation of the document structure
Directory Structure Explanation
Within each sub-directory there is a README 📖. This continiues to reinforce the idea that we need to orient the participants to this narrowed scope of the documentation. It’s there to explain the nuances of this sub-directory.
In the Problem Statements and Projects directory, there’s a dashboard file. This is to give an overview of the current status of the Problem Statements and Projects, and provide links to each of their relevant summary; maybe a README or the description document.
The Processes directory is a bit different; There is a drafts and published. Again, this is a conceptual separation. Some processes are in the works, and shouldn’t be conflated with what we’ve already formalized or documented. In a git-backed ecosystem, this separation wouldn’t be necessary, but would be implicit through branches and pull requests.
The Administration folder is deliberately loose; I don’t know what would go in there, or it’s structure. That’s up for the README to define.
In all of this process, the “loose structure” of Google Drive 📖 works against developing a shared understanding. After all, anyone can drop something into the Drive, and it’s now “live.” And we may not know about it.
This is one reason, I spent time on Conceptualizing a Process for Where and How to Publish the Thing. For a group to operate from a shared understanding requires systems for ensuring that changes in assumptions, processes, etc have some “publication” consideration. In other words, Google Drive favors a adhocracy approach. It can work, but requires more discipline.
Directory Structure Implementation Details
The above directory structure uses verbose file names. Each filename includes the name of the containing directories. This can lead to rather verbose filenames. But this convention is to address Google Drive’s search User Interface (UI 📖) constraints; namely that when you search you’re looking for file names. By adding descriptive file names that provide clues to their “path”, the hope is to create more discoverable content.
For example, in my current Google Drive context, when I search for README, I see 7 files each named “README” and no other context in that search. If I look at the tile view, I can see previews of the contents, but not their context. The list view shows the document owner. Neither of these are quite useful for understanding the README’s context.
When using most text editors when I look for files name, the finder includes the file’s path relative to the project root. In other words, for my use case, if I’m using a file system, I don’t need verbose file names but instead can rely on the verbosity of the directory names. Alas, that is no the case of Google Drive.
Conclusion
Originally, I thought to explore just a Github 📖 based strategy. However, in reviewing current practicies, I saw the convenience and current adoption of Google Drive as something to further explore. In the post, I’ve highlighted the considerations we’d need to make for Google Drive instead of Github. I have not done the same for Github, which would rquire training and buy-in from those impacted by the change. At this point, I need to bring this to the team to further discuss.