Must and Must Not: On writing documentation

The primary rule of writing documentation is: Revise it, many times, on separate days. You need to keep coming back to it, reading it with a fresh mind that hasn't thought of what you wrote for at least half a day, preferably longer. What seemed perfectly clear yesterday will come across as ambiguous today. You keep revising until the changes get smaller and start to feel cosmetic.

Your job is to write concisely, using simple, unambiguous language that's quick to read and easy to digest. It's a skill that must be learned, practiced, and honed.

It's also a good idea to explicitly spell out the meanings of "must not" etc, because people (especially non-native speakers) sometimes get confused. Example: https://github.com/kstenerud/concise-encoding/blob/master/cb...

It doesn't take up much room, but it saves a whole lot of trouble down the line.

Also helpful is the Checklist for Plain English[1]. The gist is "less is more;" fewer words are easier to understand than many words, short sections are easier to understand than long sections, and familiar words are easier to understand than something you looked up in a thesaurus.

Of course, these guides are only helpful if you already understand what you're trying to convey; that's the real secret of writing well. Figuring out the correct sequence to walk a reader from "I don't know anything about this topic" to "I understand this topic" is more art than science, and to do so well takes years of practice.

[1]: https://plainlanguage.gov/resources/checklists/checklist/

The computer scientist David Parnas had a great technique for helping his students who were having trouble writing their theses. His idea was this: every chapter and paragraph in your thesis should answer a question. Start your outline with questions. For example:

Chapter 1: What is this thesis about?

p1: What is the problem tackled in this thesis?

p2: Has there been previous work done on the problem?

p3: Can the previous work be improved?

Chapter 2: How did I approach the problem?

and so on.

Then the writer started answering the questions. The final step (usually) is to change the questions into headings or remove them.

There was an incident related to this that got a couple of German colleagues in big trouble. They were told that a specific change "must not" go into a release, it was OK for it to wait for the next patch release. They heard "must not" as the negative of "must", as it is in German. This is wrong: "you must" and "you have to" are the same, but "you must not" and "you don't have to" are not the same. They thought they were being told "you don't have to" but thought they had the freedom to get the fix to a customer sooner. It seems this caused breakage for a different customer and they were accused of being insubordinate until it was sorted out.

> It turns out that it's not necessary to have fancy formatting in order to communicate clearly; in fact, fancy formatting often distracts from the message you are trying to get across.

Man I wish the JavaScript community would grasp this better. I’m looking at you, GitBooks!

"the problem is that I'm not a writer, I'm a software engineer, "

This is a pretty common attitude, but I would argue that you are not a competent engineer unless you can properly document what you have done, plan to do, expect of other systems, etc.

It may not be a favorite part of the job, but it absolutely is a critical and fundamental part of the job.

KV is missing the point. The problem is not really with generating the documentation, so much as it is with the software engineer lacking understanding of what they are writing about, what the security processes should be. That is why the engineer is at a loss and looking for some kind of a template, to rely on others who have already done the work. With regard to tackling security processes in a startup, one could refer to NIST standards. Maybe not the most suitable per se, but a starting point.

It's good to reference RFC 2119 and using the language there.

But other than that, it seems like a terrible response to the question asked, missing the point of the original question by at least 80%. Or phrased another way, it sounds like somebody's trying to push for RFC 2119 and sacrifices giving good answers to questions.

This is helpful to get all doc authors to use the same vocabulary. One ambiguous wording that I keep seeing is "X may not do Y". Does the author mean that X possibly doesn't do Y or do they mean it's strictly forbidden that X do Y (-> "x MUST NOT do y")?

While I think there is great benefit in using concise and clear language, I highly disagree if anyone takes away the idea their documentation should be a themed after an RFC (I do enjoy reading RFCs though!)

This [0] was imo an excellent discussion on documentation that gets to the issue much more than word and formatting choices.

The short is there isn’t “documentation” as one thing, but four.

1. Tutorials where you start to finish explain it to a newbie,

2. How to guides where you explain specific tasks,

3. Discussions where you lose all formal pretext and explain your INTENT (huge) and reasoning for decisions, like you would actually explain to a person, not a robot, not some cute marketing talk

4. Technical reference that goes over the actual mechanics and the weeds that people need only once they’re working with your solution.

It was on HN at least once. [0] https://www.divio.com/blog/documentation/

Am I the only one who was initially confused by "Must Not"? As a non-native speaker, my logic was probably something along the lines of "Must Not" => "Not a must" => "You don't have to, but you can" - which of course is not what it means...

A lot of commentary here on if "MUST NOT" is too ambiguous, or not, or a problem for non-native speakers...

This makes the authors point about citation. In technical documentation any terms use like this must (MUST) be defined, either in line or by citation.

This is also part of the reason they are capitalized, to key you to the fact they are being used in a structurally important way. If you are reading them, you need to familiarize yourself with the context.

Don't write sentences. Write bullet points. Arrange those bullet points into groups. That becomes your table of contents. Continue to add more bullet points over time, and rearrange them as necessary. Eventually, you'll get the picture of what the documentation should look like. Then you can convert the bullet points into prose.

The reason you do it this way is that it's way easier to write bullets that it is to write sentences. It allows you to focus on substance instead of form. It's analogous to typing into a plain text editor and not worrying about formatting. Formatting, and form, do matter, a lot. But you can add them later.

Sorry but this seems to hit one of the age-old arguments of documentation: can you truly rely on everyone using your code downstream to read your docs?

This article makes a strong assumption "yes". Because it must, it relies on non-executable and non-verifiable documentation to implement a security gate. But for a very small performance overhead, you can likely do those checks in code, and never worry if your documentation becomes lost, outdated, or simply ignored, and more importantly, now that the requirements are embedded in executable code rather than dumb documentation, you can automated testing of the requirement.

Here are two resources I've found helpful:

https://simplystatedbusiness.com/wp-content/uploads/2013/07/... https://www.bartleby.com/141/

On a related note, does anyone remember a recent (~30d) article describing a company which disabled their Slack (or alternative) message retention in order to encourage more permanent documentation? I'm sure I saw it on HN but cannot for the life of me find it again.