
Must and Must Not: On writing documentation - amortize
https://queue.acm.org/detail.cfm?id=3341158
======
kstenerud
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...](https://github.com/kstenerud/concise-
encoding/blob/master/cbe-specification.md#terms)

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

~~~
tejohnso
> 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.

Agree completely. Can you recommend any resources that emphasize this point
and provide similar helpful documentation guidelines?

~~~
atoav
Another idea is to try on different personas: Put yourself into different
roles, e.g. the person who just looks at the examples and skips wall of texts,
the person who wants to read up on every nook and crany, the person who has no
technical background etc.

The cool thing about text is, that it can be many things to many people and
this is even more true with hyperlinks. Try to cover all bases at least a
little bit and people will ignore the stuff they dislike and go after the
stuff they like.

------
thomascgalvin
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/](https://plainlanguage.gov/resources/checklists/checklist/)

~~~
musingsole
There are some utilities out there that will give your writing a education
grade level (such as the Hemingway Editor:
[http://www.hemingwayapp.com/](http://www.hemingwayapp.com/)). In the case of
technical documentation, you want to aim for the lowest grade level you can.
Your technical words and descriptions of systems will necessarily push the
grade level higher. Every non-technical phrase would ideally be written as
simply as possible.

~~~
ergothus
I've taken some technical texts I've written in the past and run them through
the xkcd simplifier - it identifies words that are not in the 1000 most common
English words (? something like that).

[https://xkcd.com/simplewriter/](https://xkcd.com/simplewriter/)

I keep the words that truly add value to the project, and replace all the
others with more simple ways of saying whatever I am trying to say. Usually in
the process I lose a few lines of text (occasionally I can a few bullet points
instead). It's a pretty good experience to go through (for example, this post
fails. A lot.)

~~~
hiccuphippo
It would be nice to have something like this with common words used in
programming contexts added to it. Maybe as a VSCode plugin or something.

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

~~~
nsm
Simon Peyton-Jones (of Haskell fame) also has a similar talk+slides that I
find valuable to periodically re-visit. [https://www.microsoft.com/en-
us/research/academic-program/wr...](https://www.microsoft.com/en-
us/research/academic-program/write-great-research-paper/)

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

~~~
yakshaving_jgt
I think the more illustrative comparison in English here would be "you must
not" vs "it is not a must to".

~~~
PeterisP
The difference between "must not" vs "need not"; in some languages the
equivalent word functions like english "need".

------
CGamesPlay
> 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!

~~~
52-6F-62
At least they still render with JS disabled. Gotta love when a text document
won't render without script bundles.

------
ska
"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.

~~~
zahrc
‘If you can’t explain it simply, you don’t understand it.’

Also, writing documentations helps me understanding and reflect.

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

~~~
SlowRobotAhead
I’ve yet to see a solid execution of how to convey INTENT.

It’s the why vs what issue scaled back a layer. With software and systems you
want the user to do solve many problems with your solution, but you never let
them know your exact intent and that causes shoehorning.

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

------
classified
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")?

~~~
rocqua
To me, that reads as 'X is not allowed to do Y' without any ambiguity until
you pointed it out and I thought hard about it.

Wondering whether that is common response or not.

~~~
leetcrew
it's an ambiguous parse for sure, but the meaning is usually clear in context.
it's possible to create a really ambiguous example though, e.g. "when pinged,
the server may not respond". is this stating a requirement that the server
never responds to pings, or is it a warning that the server doesn't always
respond?

------
SlowRobotAhead
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/](https://www.divio.com/blog/documentation/)

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

~~~
brlewis
The meaning is unambiguous to native speakers. In "you must not run" the word
"not" always modifies "run", never "must".

~~~
bloak
The meaning is as if "not" modified "run", but syntactically "not" is attached
to "must", I think. You can probably convince yourself of that by considering
a sentence such as: they can yet must not run. So you are absolutely right to
be confused by such sentences. There is something weird going on.

~~~
brlewis
See wiml's sibling comment for a correct reason why someone might be confused
by such sentences. "Not" negates, so it is definitely not modifying "must".
Clearly the word being negated is "run".

~~~
bloak
Believe it or not, as a native speaker of English who has studied linguistics,
I do know that "not" negates, but thanks anyway.

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

~~~
bitminer
My system engineering experience avoided "must" as insufficiently specific.

We used "shall" and avoided "not". Because testing: how do you prove a "not"?

Source: 35 years of SE

~~~
ska
I've tended to use SHALL and MAY for the same reasons, but it is important
they are defined anyway, somewhere everyone agrees.

Agree "not" is tougher, and best avoided when you can.

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

~~~
lonelappde
And once you have write the bullet points, stop and ask if the people really
adds anything.

Prose is could for creating emotion in the reader, but not for conveying
technical information. Know your goals.

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

~~~
baroffoos
Yeah, I prefer unit tests over docs. Rather than writing a document saying
"Make sure X does Y" Just write a spec checking that X does Y and if it ever
stops doing that there will be a descriptive error in the CI.

Docs and comments go out of date and people don't know they exist/where to
find them. Unit tests are always checked and always maintained.

------
apotatopot
Here are two resources I've found helpful:

[https://simplystatedbusiness.com/wp-
content/uploads/2013/07/...](https://simplystatedbusiness.com/wp-
content/uploads/2013/07/Simple-Words.pdf)
[https://www.bartleby.com/141/](https://www.bartleby.com/141/)

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

