Writing Documentation When You Aren't a Technical Writer
Great articles (there is a part 2 here: 
<a href="https:&#x2F;&#x2F;blog.stoplight.io&#x2F;writing-documentation-when-you-arent-a-technical-writer-part-two-59997587cc2a?source=collection_home---1------0----------------" rel="nofollow">https:&#x2F;&#x2F;blog.stoplight.io&#x2F;writing-documentation-when-you-are...</a> )<p>The article is about API documentation, but the points apply to every documentation.<p>I think however that a few things are missing in the articles:<p>1- an OVERVIEW&#x2F;INTENT page&#x2F;paragraph.<p>This is THE thing that is missing in almost every -if not all- documentation I&#x27;ve ever read.<p>An example that I always use to illustrate the point: the &quot;File&quot; API. In EVERY documentation I&#x27;ve ever seen, the usage of each function&#x2F;method is detailled, but NOT why some function must be used before others (opening a file is NOT an obvious concept); the concepts (what is a file?), the workflow are NEVER explained.<p>And Files are basic stuff, what about GUIs? Ever used a big GUI toolset? It&#x27;s miserable! They never include the high level stuff, you have to dig a lot and if you are lucky, maybe you&#x27;ll find a blog womewhere that gives a few insights in the mind of the creators. IF you are lucky. So you end up using the wrong type of widget or function (because they look alike) until you crash &amp; burn and realize that it was the wrong choice for your purpose, because NOTHING is explained, you have to discover everything at your cost.<p>2- graphics&#x2F;workflow charts<p>This is related to my first point. When I write documentation I include -at least- one high level graphic that shows how the various parts of the system interact, sometimes a flowchart or a Finite-state diagram (when a FSM is used, obviously).<p>-----<p>When I give a module to my coworkers (be they testers or users of my API), I give them that additional documentation which makes it MUCH easier to understand and test&#x2F;use. What I find stunning is that I&#x27;m always the ONLY ONE to do so! At most my coworkers will write _some_ documentation to explain a few difficult points, but it will mostly be comments, not documentation for an user of their API&#x2F;module. And if you point it out, the reaction will range from &quot;I&#x27;ve no interest in that&quot; to &quot;it&#x27;s not necessary, the code talks for itself&quot;... To them, the -automatically generated- JavaDoc comments are &quot;enough&quot;, which is total B.S.<p>The most infuriating is that all this -undocumented- code is always the result of a HUGE amount of work and dedication. But it is invariably cruely hobbled by that missing step: helping the users use it properly. I see it everyday in Free&#x2F;Open source tools, and I&#x27;ve seen it in every project in the companies I&#x27;ve worked with (except mine of course)...<p>So you spend lots of time trying to understand how the stupid thing is supposed to work instead of doing your real work.<p>There is a LONG way before the importance of documentation (and comments) is accepted as what it is: VITAL. Unfortunately, as for testing and security, management not only don&#x27;t encourage the practice, but they often discourage it (poo-pooing -or worse- such concerns).