The Art of The Documentation
Earlier this week I was having a conversation with a co-worker and the subject of documentation came up.? As someone who often reviews promo packets, I’m always impressed by both the quality and quantity of artifacts produced by our engineers. ? But there are also times when I find myself wishing there was more or less documentation to look at. ? Today, I thought I would share some of the best practices that have served me well in my own documentation journey.
When to document.? ? My general rule of thumb is to write documentation whenever one or two conversations cannot scale to the number of eyeballs or touch points, the outcome I seek requires.? An example of this constraint is an async audience that may have ongoing interest in whatever is being documented.? So be sure to write documentation only when it adds clear value to others in the service of the larger goal. ? On the flip side, if you are struggling to clearly articulate the desired outcome for that documentation, there is a good chance you may be producing documentation where none is needed.
“If I had more time, I would have written a shorter letter.” — Marcus Tullius Cicero
How to document.? Different documents serve different purposes but with few exceptions, they should all be written with an audience in mind. ? The right amount of documentation should require the least amount of writing needed to convey the most to the right audience.? Many times, engineers optimize for the largest possible audience and end up with excessive documentation that misses the mark for the right audience. ? And finally, remember to be concise because any documentation bloat will likely detract from the value your audience get by muddling the message. So know your audience and keep it simple.
领英推荐
Pro Tip on the How:? If you are someone who hates writing? like a lot of engineers do, always remember that documentation is often a group exercise and sometimes, all you have to do is get the ball rolling.? In my experience, some of the best documentation I have seen is a collaboration between several stakeholders that captured different POVs and was stress tested from different angles.
What are some of your own best practices and tips when it comes to documentation?
To see my writings beyond "Stuff Engineers Say,"?visit my articles page?or?follow me.
Staff Technical Program Manager @ LinkedIn | M.Sc | PMP? | AI/GenAI
2 年Once the doc is started, don't abandon it, unless no longer needed. Iterate on it (includes reviews) until done, find time. The lose of synergy can spoil your effort.
Educator, Economist, and Composer| Situating Niches within Pitches
2 年Too much is when it's just like a lexicon or dictionary. Too little is when it is enigmatic like some Mensa test. Just nice is when we can't subtract and make people more knowledgeable or interested. Users can use it as a map to find their way around.
Staff Software Engineer @ LinkedIn | ex-Amazon
2 年Thanks for a great article emphasizing something very close to me. One thing that works well for me is treating writing docs as part of a software development lifecycle. Don’t delegate writing docs to the last minute, instead sketch out a skeleton, keep it updated as you evolve the code and add finishing touches to it towards the end of the development cycle to keep it true to what has been implemented.
I struggle with getting the first few lines together and once I get going it flows more naturally. One thing that has served me well over the years is to actually think and write like an engineer and not try to emulate other peoples’ styles. I often write bullet points and structure it around “what”, “why”, “how” and “when” with a FAQ section. This takes away the fluff that I have to think about which often is a big source of stress for me.