As I’ve been refining my approach to work, a phrase has been sticking in my mind:
Lead with documentation
What this means in practice is when I start working on anything that requires a little up front thought, architecture, or planning, the first thing I do is open up the documentation for the project and start writing. If collaboration/discussion is required, I open a pull request to facilitate discussion. However, the approach is still documented in the repo files, not in the PR, Github issue, etc.
This is very different than how most people work, but I’m finding it enjoyable and productive. It is taking effort to switch, as I still tend to put too much documentation in Github issues. Old habits die hard and change takes time.
For this approach to be effective, documentation needs to be frictionless. For me, this means Markdown – preferably in the same repo as the design/source files. Then it is easy to edit code and docs in the same editor.
Some of the benefits to this approach:
when you are done with a task, the documentation is already done. Doing documentation after the fact is a rather distasteful task. However, if it s done before the task, it is very engaging.
Upon reflection, it is ironic that I should have written this first in the tmpdir handbook where it would become part of a long-living, permanent document, and then linked/discussed it here. Fixed now. Change is hard.
This is an important point in my opinion, all the OpenBSD documentation is stored in the sources trees, they must be committed by someone with a commit access. Wiki often have orphan pages, outdated information, duplicates pages with contrary content. While they can be rich and useful, their content often tend to rot if the community doesn’t spend a huge time to maintain them.
Thinking about this a little more, in a successful wiki, like Wikipedia, the documentation is the end goal, so it is the focus – so a Wiki works well there. In product/project documentation, the documentation is NOT the end goal, so it is not the focus and can be easily abandoned. This is interesting – I think I’ve finally figured out why Wiki’s generally don’t work in companies.
Thus, for successful project documentation, you have to structure things for success:
docs must live in repos as close to design/code files as possible so they can be maintained as part of your normal development process.
documentation must be in a format that is easy to review, edit, and maintain (Markdown seems to be the pragmatic choice)
documentation must be open, accessible, and easily found. Again, Markdown shines here because you can easily link from one document to the next. You are not limited by the strict hierarchy of a filesystem. It is also easily viewed in the Git management tool (Gitea, Github, Gitlab, etc) without opening the file in another application.
you must develop a culture and workflow where:
knowledge, decisions, theory of operation, etc is captured in documentation, not lost in the black hole of email and meeting discussion.
documentation is integral with the development process
discussions center around documentation
This all is hard – really, really hard. But, I’m convinced it is one of the great differentiators.
Some things you should consider not doing when working in a development team:
email a document. Instead check it into a repo and email a link.
write long technical information in an email. This information will be lost, instead write it in a document, and then send a link.
extensively discuss things in email if there are better mediums like PRs, issues, forums, etc. where the discussion is accessible to anyone who has access and throughout time.
Again, this is really, really hard. Most people find security in being the gatekeepers of their domain. But, if you want any of your work to transcend yourself, you have to do things differently.