[LarryL]

Great articles (there is a part 2 here: https://blog.stoplight.io/writing-documentation-when-you-are... )

The article is about API documentation, but the points apply to every documentation.

I think however that a few things are missing in the articles:

1- an OVERVIEW/INTENT page/paragraph.

This is THE thing that is missing in almost every -if not all- documentation I've ever read.

An example that I always use to illustrate the point: the "File" API. In EVERY documentation I've ever seen, the usage of each function/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.

And Files are basic stuff, what about GUIs? Ever used a big GUI toolset? It's miserable! They never include the high level stuff, you have to dig a lot and if you are lucky, maybe you'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 & burn and realize that it was the wrong choice for your purpose, because NOTHING is explained, you have to discover everything at your cost.

2- graphics/workflow charts

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).

-----

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/use. What I find stunning is that I'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/module. And if you point it out, the reaction will range from "I've no interest in that" to "it's not necessary, the code talks for itself"... To them, the -automatically generated- JavaDoc comments are "enough", which is total B.S.

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/Open source tools, and I've seen it in every project in the companies I've worked with (except mine of course)...

So you spend lots of time trying to understand how the stupid thing is supposed to work instead of doing your real work.

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't encourage the practice, but they often discourage it (poo-pooing -or worse- such concerns).

[slx26]

I agree with most of your ideas, and I usually apply them myself. But wanted to ask about graphics and charts, do you use any specific tool? They can be time-consuming to get right and update.

Also, I believe a problem here is that on large organizations and codebases many programmers don't really understand themselves the relationships/interactions between systems, or people setting the standards think overviews are hard to standardize, or they think other people think documentation is a pain to write so they try to minimize the work needed to get it "right".

EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).

[LarryL]

> graphics and charts, do you use any specific tool?

Usually, I used Visio, not really by choice but because it was available and sometimes used by other coworkers (usually for the specs flowcharts). There was another tool available, that was used in one of those companies, it was better than Visio, but I don't remember the name, unfortunately, due to a insufficient number of licenses, I could not use it.

When I do such stuff on my Linux box, I use various flowchart/diagram tools like Dia (and another one whose name I forget). I've also experimented with various text-based solution (LaTeX-based & the like), but with mitigated satisfaction: those solutions where too heavy & cumbersome for my use case.

As you wrote, those ARE time consuming and have the usual update problem. But that cost is really offset by the benefit of clarity. When _I_ gave a module to the testers team, I gave them a brief (15 to 20 minutes max) presentation and my documents & usually never heard again from them (except when they found a bug of course), while with the other modules (made by my coworkers), I saw them asking for more information all the time...

> EDIT: came up with a better way to put it: documentation should deal with what a system does, why and where, then how it achieves so in a broad sense, and finally deal with the implementation details (which is the only part we are kinda handling nowadays, as you explained).

You describe _exactly_ the problem. And I've been fighting hard to make that simple idea enter in my coworkers -thick- skulls, but with not much success: they often do acknowledge the problem, but either don't care (disgruntled or not professional) or are too lazy or are overworked and take shortcuts, not realizing that medium and long-term they would in fact GAIN some time... As for the management, I've lost all hope, no amount of discussion can enlight them (they only see "THE CODE").

[pronoiac]

I'm not the original poster, but Mermaid - https://github.com/knsv/mermaid - looks like a decent way to put easy-to-edit graphs in Markdown.

I haven't had a chance to use it yet, but I want to. It's not part of Github Flavored Markdown.

[uvtc]

> - an OVERVIEW/INTENT page/paragraph.

Yes.

I wrote a little tool ([Rippledoc](http://www.unexpected-vortices.com/sw/rippledoc/index.html)) for processing a docs directory of markdown files into a navigable whole, and recently updated it to be able to use the project README.md (the presumed overview/intent doc) to encourage having that front page be overview/intent.