If you’re an engineer, or have ever been an engineer and have since moved on to management or some other dreadful thing, then I’m sure you’ve seen documentation live and die in the trenches of confluence, notion, or a company wiki. A lone reference doc describing some then-novel esoteric service that was developed and then quickly abandoned; left to drive 8% of your business through a chunk of code only Tyler understands, if only he were still with us…

Everybody understands that documentation is important. It ensures asynchronous knowledge transfer, enshrines technical decisions, reduces time to error resolution, and serves to make your application more modular and maintainable. These all combine to make sure your business can pivot early and when necessary, allows your business to maintain first to market competitive advantages, and enables your engineering team to keep users and customers happy with quick (and correct) responses. However, I’m not here to convince you that documentation is important (If you don’t agree then this isn’t the post for you!); instead I’ll attempt to answer the question of how to make your documentation process a successful and integral piece of your business. (This post is primarily aimed at mid-market “scale-up” phase companies. I fully understand that the process and politics of new global initiatives vary wildly at larger scales; however some information may be beneficial for a team-wide process)

Documentation is a team effort

First thing’s first: Who owns this documentation initiative? Often one of the more frustrating aspects of software development is being pushed to tighter and tighter deadlines, while knowing full-well that writing good, coherent, documentation is time consuming. Developers aren’t all natural technical writers and thorough documentation will take some time to write, proof, edit, and rework. This leads us to the ages-old point of contention that engineers don’t get enough time to write documentation and managers don’t see the engineers they manage writing documentation so, in turn, don’t allot the time for it.

Is documentation a top-down or bottom-up initiative? Well, it’s both!

Me, just now

I like to call this approach to introducing concepts “sideloading”. It requires effort from all sides, just in different capacities. In my experience managers will not grant time for a process they don’t see value in, so this process starts with the top-down approach of ensuring that management understands the value gained by writing good documentation.

However, it does fall to the engineers to actually write that documentation, and my advice is: don’t ask for permission. I spent much of my early career asking my managers “Can we set aside some time to write documentation on this?”. This was almost always met with a response along the lines of: “Let’s get the project finished and if we have time afterwards we can write something in retrospect.”. However, “retrospect” never came as the next feature had a shorter and tighter deadline that came earlier and earlier. The mindset that helped me overcome this nagging desire to ask was to realize that documentation (along with other “administrative” pieces of software development like unit tests…) is just part of developing software. Documentation and testing is no different than writing loops or creating classes, it’s all part of the process to ship working code. And, nobody ever asks their boss if they have permission to write a loop or create a class!

Doesn’t matter, just write it down…

Now, assuming that management agrees documentation is valuable and the engineers are all writing rogue documentation, how can you ensure the documentation being written is complete and organized enough to be valuable for all those reasons I listed above? Well, there are one hundred different ways to organize and taxonomize your documentation, but to be frank nobody reading the documentation is going to care and they’ll almost always just use the search box, bypassing all of your folders, categorization, and tagging. The single most important thing is to just get your thoughts out of your head, off slack, out of meetings, and onto “paper”.

Before anyone thinks of bucketing, tagging paradigms, completeness metrics, hiring technical writers, or organization; make sure you have a culture of just getting your thoughts to some public repository. The one caveat to this approach is you should ensure that all documentation is written in the same singular location. This improves findability and also lowers the barrier to entry for someone who wants to contribute to this documentation for the first time, (avoiding common thoughts such as “Well we put design docs here, and docs about business processes here, and docs about our apis in one place, but our nodejs lives here for such and such reason).

Form matters much less than function at this phase. If you are having trouble finding the time to write properly edited and proofed documentation it is perfectly ok to ping someone on slack and ask “Hey, how does module x and y work?”, then copy/pasting their entire response into confluence, hitting “publish” and calling it a day. This is ugly, but infinitely better than nothing.

Lastly, if you have an existing, yet fragmented, knowledge repository I have found it is beneficial to just take the time, crack a few sodas, and copy/paste the writings from the old wiki to the new location. It took me a couple weeks of like 30-60 mins each day to do something similar before, and it is one of the more critical requirements to ensuring your knowledge repository is actually used.

Have some kind of framework or process

Once you have the culture of just writing things down, it is somewhat useful to categorize your documentation in a way that encourages exploratory learning; which is increasingly more valuable as your company expands and hires more. The important thing here is not to bikeshed over solutions and worry about ifs and buts, just find some taxonomy that works for you and document it so people know it exists. There are some formal types of documentation (Like Swagger, ideation/design frameworks, Architectural Decision Records, etc.) that won’t fit into your framework anyway so there is no point attempting to hamfist it all in.

As an addendum to the above: allow for linking out to specific documentation from within the central repository. It makes no sense to put diagrams in a wiki or confluence, they belong in lucidchart or archimate, just ensure that a path to access to those documents is available through the central documentation repo.

The primary focus here is to ensure your documentation is helpful so it will actually be read and utilized. People will be hard pressed to to take issue with a process they directly benefit from; so make sure it’s beneficial!

For managers: recognize contributors

As a manager you are the primary arbiter of feedback and recognition for your employees. If you recognize the value inherent in strong documentation, then I urge you to take the time to recognize your employees that are writing this documentation. To foster a culture of documentation: publicly uplift engineers whom make the effort to build technical writing into their development process. This means commending them in slack, on meetings, and when it comes time for performance reviews nothing speaks louder than financial compensation.

It is also your job to read the documentation that is relevant to you. The minute your lack of reading comprehension forces you to ask a question that was covered in a document an engineer JUST sent you, is the moment you trash months of effort trying to build a documentation-centric culture. You need to make writing documentation a positive part of the SDLC to guarantee it doesn’t become a thankless, bitter, task.

Gatekeepers need not apply

This is a reiteration of the first point phrased from an organizational level.

Do not gatekeep your documentation, above all else getting thoughts out of heads and onto paper is the most critical objective. If someone is assigned to oversee documentation ensure they are not overly critical of things like grammar, taxonomy, or organization: this can sap the will to live from anyone just trying to do a good thing. The less rewarding and engaging your process of documentation is the less likely people are to contribute.

contributor : Hey, I just wrote this cool overview on the new authentication system! It’s several thousand words and I made some diagrams to go along with it, let me know if I missed anything!

gatekeeper : You misspelled “authentication” on line 472, position 12. Fix it.

contributor : I mean, you have edit capabilities on the document, you could have just fixed it yourself. Is there anything else wrong with the content of the document?

// This shows a poor interaction with an individual that is too hyper focused on the presentation of a document over the content. This can discourage and demoralize otherwise enthusiastic contributors.

Lastly, make your documentation accessible in as many ways as possible. Before cordoning off a section of your organization from others, ask yourself: “Is it necessary that bob from accounting be restricted from viewing reference material about the banking service?”. It may make ontological sense to keep documentation on a need-to-know basis, but it can severely hinder cross-sectional communication. Remember: you want as much buy-in as possible on your process to ensure it doesn’t die coughing in a ditch.

Let’s recap

• Just start writing. Engineers: don’t ask for permission. The more content that is written the more valuable the process becomes and the higher chance of success the initiative has.
• Make sure your documentation is useful to newcomers and those otherwise unfamiliar with the documentation process by way of some organizational framework
• Do not over-do it on the taxonomical requirements. Make it useful but no more.
• Managers: Reward contributors. Publicly, hierarchically, and financially; put your money where your mouth is if you truly believe documentation is an important and valuable part of the SDLC
• Make documentation fun to engage with. Discourage pedantry and overly critical gatekeepers.
• Make your knowledge repository as accessible as feasibly possible.

Finally, in as big of letters as my blogging platform will allow me…

DO NOT ASK FOR PERMISSON!