
Ask HN: What is key to good technical documentation? - jnxx
Imagine you are a junior software developer who is entering a relatively large and complex project with 150,000 lines of code. It is not some web software, but something way more complex, say an embedded system, or a navigation system,  or a digital camera, or maybe a complex device for medical imaging. It is a lot of code in different languages. What you know is that the major aspects are working but there still might be some problems.<p>And of course, management is eager for you to get stuff up and running, as the project is already severely delayed, needs to be shipped as soon as possible, and the customers and investors are getting impatient.<p>There is only one problem - all the three senior engineers which were working on the codebase have left suddenly, only their  manager is still there, and you have to start with reading and understanding the code, and what needs to be done. It is somewhat commented, but, of course, it is not easy to understand. And as it looks, the previous developers did not had any time to leave you proper technical documentation! What are you going to tell the manager?<p>But then, suddenly, a fairy godmother appears, which has a magic wand in her hand. It is a kind and witty documentation fairy, and she says: &quot;I will fulfil you a single wish. By my magical powers, I will give you exactly the documentation which you think is most important. It can be anything you want. Anything! The only condition is, it must not be more than a good software developer can produce in a month.&quot;<p>What do you wish for?
======
pytester
* Examples. Realistic, complete, useful examples that demonstrate the software being used in the manner it is intended.

* Glossary for any special terminology that can't just be googled - especially project specific terminology that may be confusing, and _double especially_ terms or phrases which are used _slightly differently_ to the way everybody else uses them (e.g. 'user' means something slightly different almost everywhere).

* Lots of "why" describing why the software behaves in ways that seem surprising at first glance.

~~~
trynewideas
Seconded on examples, but example code needs to be integrated into software
testing for projects that are frequently updated. Broken examples are arguably
worse than none.

Even less arguable is when examples that worked are broken by an update and
remain unchanged--they'll work for people on outdated versions but break when
they upgrade, and also break for new users, and nothing will sufficiently
explain why.

Please add your documentation examples to your testing pipeline (or write
tests clearly enough that they can be good examples, and just use those).

~~~
ShamelessC
> Please add your documentation examples to your testing pipeline (or write
> tests clearly enough that they can be good examples, and just use those).

This seems like a pretty good practice to me. Are there any good testing
libraries for keeping your documentation examples tested and up to date?

~~~
ithkuil
A language specific answer: The testing package of the Go standard library has
a built-in support for examples. They are executed as part of the tests, but
are rendered by the documentation generator as examples. This obviously only
solves the problem of library writes that want to expose examples of library
usage (and ensure they don't get stale)

~~~
adamhepner
This is such an amazing feature. I wish it got picked up by other major
languages and became a standard practice.

------
teeray
The best technical documentation I’ve seen at a company was written by a
technical writer. Most companies don’t like hearing this because it costs more
than adding an additional drag on your development teams to also become solid
writers (good writing is real, time-consuming work). Having someone whose job
it was to start from the perspective of your users, ask questions of the dev
team along the way, and document the journey yielded enormously useful docs.

~~~
Ididntdothis
I work in medical devices so we have to produce a ton of documentation in a
very specific format. I never understood why our devs have to spend a ton of
time on producing not very good documents. We have a few tech writers who
produce much better work but they are completely overloaded. I don't
understand why management doesn't hire more writers to free up the devs and
also to produce better docs faster.

~~~
jnxx
I guess that not everything which is required is helpful at all for the actual
developers, is it?

~~~
Ididntdothis
The content may be useful but there is a lot of regulation what to document
when and to what level. That knowledge is not very useful for devs.

------
mooreds
A couple of things:

* High level architecture (what pieces talk to each other, how they communicate, what they do)

* A list of 'here be dragons' areas, places where the code is gnarly

* A bug database, which will give you history of decisions

Then I'd ask the manager/product owner for a requirements document (or
documents), as that should be something a non technical person can/has put
together.

Frankly, though outside the scope of your question, I would also look at
hiring one of the departed senior devs on a contract basis, just to ask
questions of. I have offered this for the past few jobs I have left and there
are times when 15 minutes of my time could save a few hours of investigation.

~~~
ka0lin
Is this an improvement over for example the Eclipse foundation's pile of high
level architecture, bug database and here be dragons-areas?

~~~
mooreds
I am not sure what you mean?

------
tpmx
I wish for documentation of

1\. _Key_ data structures

2\. Code layout/architecture (what modules/layers calls which modules/layers,
etc)

I like Blender's example for how to do this:
[https://www.blender.org/bf/codelayout.jpg](https://www.blender.org/bf/codelayout.jpg)

These also tend to be relatively static so they don't need to be updated every
month.

~~~
jnxx
Oh _this_ , yes!

I remember reading "Practice of Programming" by Brian Kernighan and Rob Pike
(which is a really, really fantastic book!), and it talks about the importance
of data structures.

[https://en.wikipedia.org/wiki/The_Practice_of_Programming](https://en.wikipedia.org/wiki/The_Practice_of_Programming)

This comes up again and again, and it is so true! The core data structures are
one of the most important aspects of a program. In fact, when I start to write
a program, I think about the central data structures first. It is clear, that
to a programmer who takes over a project, they need to be explained as one of
the first and most important things.

~~~
tpmx
Hey, glad you liked my two wishes.

Yes, data structures usually define programs. The code tends to follow more or
less naturally from the data structure and the interactions with it.

If you misdesign the key data structures of your program it will balloon in
size and complexity. Edge case bugs will swallow you alive.

If you make it just right typically (almost) everything will fall in place.
This is still true in 2019, even with all of the distributed aspects that have
been added to most programs/systems of programs.

I agree about that book, it's good stuff.

------
tetha
I think good documentation needs to be written with a few decisions in mind:
What role, what kind of person is this section written for, and what kind of
task does the reader have at the moment?

There should be sections on familiarizing yourself with the system - which
persistence APIs are used, what are the broad dataflows, where are things
dispatched into greater detail, what are active parts in the system. And I did
say "sections", because a developer, a system operator, a customer supporter
and a consultant implementing the system all need different kinds of
information and levels of detail.

There should also be sections on handling known task structures, known
troubleshooting guidelines, again, with a focus on the role of the current
reader. If content has to be searchable via elasticsearch, there should be
focused documentation: How do I get an entity into elasticsearch? How do I
connect an actuator setting on a pin with a setting on the UI page? These
sections should be mostly like a todo-list.

In order to write something like that, imagine just explaining the system to
someone and write most of that down. I've found that this results in very
effective documentation. It's usually simple to read, and it's also easy to
understand if you should read this block or not. For example, if something
says "This is scoped for developers", I might skip it.

------
MichaelMoser123
I would ask the documentation fairy to come up with sequence diagrams for the
most common flows/use cases. That used to be the winning argument whenever i
have to come up with some docs. I think that sequence diagrams are the killer
feature of UML -everyone gets the message.

~~~
bob1029
I share this sentiment regarding diagrams. Any time I sense that a design or
requirements discussion is starting to lose track of all the various edge
cases of a particular business process, I will draw out a state diagram of
that process and put it into an email or message to the team. 9/10 times this
either immediately ends the back-and-forth, or quickly narrows down the actual
concerns to a few particular items.

I am consistently amazed by how quickly these diagrams can convey complex
business requirements to non-technical people. I could write 30 pages of
email, or draw 1 state machine on my whiteboard and snap a photo of it.
Someone should try to run the math on information density of a state diagram
vs a verbal or written communication of the same requirements. I would bet
there are a few orders of magnitude of delta in there based on my experiences.

~~~
proverbialbunny
If you don't mind the curiosity, what software do you use to draw state
diagrams?

~~~
bob1029
I just draw them on a whiteboard next to my desk and then capture using
something like Office Lens (it has a really good mode for whiteboard).

It's way faster and easier than doing it in software. This allows you to
iterate really quickly using rough sketch diagrams (also helps to open your
mind up since it's just you and the board), and then once everyone agrees on
the design someone can take your whiteboard sketch and turn it into a
computer-generated diagram for the final documentation.

We have actually found very few cases where we need to have 'formalized'
diagrams generated using software. Most of them just live in our GitHub issues
and pull requests. With enough practice, your hand-drawn diagrams can look
good enough to ship directly to a client for approval. If we do need to make a
computer-generated drawing, we just use some web tool like draw.io or use a
local copy of Visio.

------
ChrisSD
I know I'm going against the spirit of this hypothetical but the trouble with
good technical documentation is it can quickly become bad technical
documentation. It needs constant maintenance over the long term. Every patch
that's committed to the code needs to be evaluated for how it impacts the
docs. Preferably changes to the docs should be done via a collaboration with
the patch author(s) and a documentation expert (aka someone who is good at
writing technical documentation and is familiar with the conventions of this
specific document).

~~~
jnxx
That it is clearly something that could (and might should) have been done
before. But. let's stick to situation described and accept that it is way to
late to do that any more.

------
mlthoughts2018
Well-documented tests. Why are you testing something? Why do you expect the
output to be something? What is the high level purpose of the test?

High level breakdown of the code structure. What is each module / package /
namespace intended for? Why is it laid out in the certain hierarchy it’s in?
If I have a question about some functionality, how do I map it to a subset of
the code?

Who are the stakeholders? Who will get mad if this breaks and why? How many
systems does this depend on / integrate with? How do I contact those people?

What are the data flow or job flows? Does a build get triggered in CI? Is the
code published as a library? Does a web service get deployed? Does a human
have to compile something and then rsync it to a production server every
Tuesday or else everything crashes? What are all the regular tasks? Why is
each one needed, how can a test version be run?

Aside from that, then just the basics:

\- all functions (or all exportable functions) have consistently formatted
docstrings

\- docs are concise most of the time, but overly verbose in any “danger”
sections of code that rely on unusual, specific or brittle logic.

\- well documented description of project version control. What are all the
usual code management tasks someone needs to do, and why? What is your
strategy for hotfixes, releases, rollbacks, sharing branches, etc.

------
slics
As a developer myself for many years, I take the following steps for a new
project: 1- Familiarize yourself with the application, by using / testing all
its functions

2- Understand the workflows within the user interface and then map each one of
the workflows / business processes to the logical code and the logical code to
the database calls / tables.

3- Once you have built that mapping (tree structure) then you can tackle each
one of those functions without feeling lost in the entire code baseline

4- As you work on each of the workflows/ business processes you can start
comment the code in your terms

5- IntelliJ provides functions to conduct dependency mapping of the code, and
database tables to make sure you don’t have circular dependencies.

6- Once you have completed the walk through and identified the workflows /
functions / business processes you can than put a weight on each of those.
Large, Medium, Small size.

7- After completing that sizing, sit down with your manager and help him
understand what each one of those means in terms of cost, schedule and
performance.

8- if none of the above is done, you will have a really hard time coming up
with a way to explain to the manager what will it take or when will it be done
and how many people will it take if they give you a date to finish. Just
because someone wants something done in their time, doesn’t mean it can be
done in that time.

Last thought: please don’t get discouraged, if you feel stressed and pressured
already, you have lost the battle. Do the best you can with the tools you
have, even if it’s not someone else’s best.

~~~
jnxx
Interesting. That sound like what is most helpful for a new developer is any
information which would help him to do the mapping, to "connect the dots", is
this correct?

I am wondering if it would help to have a document which takes the whole list
of requirements from the requirements specification, and explains how each
requirement is realized in the code. (Or of course, if it is still missing, in
which way and where it is missing, and what would need to be done to add it).

~~~
slics
Usually requirements are at a high level and if the previous team broke them
down further in (scrum terms) user stories it would be more beneficial. If the
stories are not available, then I would consider looking at the complete/done
requirements first then worry about the new requirements. The intent is for
you to understand what the application does and what functions are executed
while you perform a given business process / workflow.

(Edit) Forgot to mention one important factor. Make sure to build a good
relationship with your manager so that he understands that you are doing
everything you can to make this work. The conversation is better understood
when the relationship is there. Keep him aware of the work you are doing so he
understands it as well, and he will have the data upfront to share with the
customers.

------
WheelsAtLarge
People hate to update docs so the majority of the time it's out of date even
if it was the best ever at one time. I was never told this but reading a ball
of undocumented code is part of the job so don't ever expect documentation
when you start a job, especially at a startup.

Here are a few things that would make life easier.

\- reduce the code's complexity. Some old-time programmers want to show off
their skills at the cost of simplicity. Ya, ya you're god's gift to
programming but the real skill is to program in a way that's easy to
understand. And also saving memory is not your primary goal anymore.

\- easy to update

\- Summary of the software's function

-Major sections of the code should be titled and explained as briefly as possible incode.

\- Docs should be part of the code review. I had a software package that would
fail if the code was updated and the comments had not or the other way around.
It was easy to disable but at least it made you think.

\- Buy in from the management on keeping docs up to date. Very hard, managers
want results not docs

-Regular review of the docs. Again, hard to achieve

\- Make sure you don't abuse the manager's trust. If you say you are updating
docs, you better be doing that.

------
piinbinary
Documentation should explain why things are the way they are. With sufficient
effort, you can look at a piece of code to figure out what algorithm it
implements, but there is no amount of reading that will tell you why that
algorithm is the right one to use. There should be a way to trace this "why"
all the way up to the business reason.

Documentation should also provide mental shortcuts. Rather than forcing you to
figure out what algorithm the code implements, it could just tell you.

It should also tell you things that are surprising, and might accidentally
miss or misinterpret.

Documentation should tell you information that you can't just as easily glean
from the code. A `doTransmorgification()` method doesn't need the comment `//
does transmorgification`.

Documentation shouldn't attempt too tell you everything with one form of
documentation. Documentation on a line or method or class is good for one sort
of information, but it doesn't cover the overall architecture of the program.
That is often best left as a separate piece of documentation.

It should consider the reader. Is the reader looking for an introduction to
how to use this library, or are they looking for what property the method has
in some edge case?

Documentation should use the easiest to follow, least technical language it
can without being inaccurate. It's not an academic paper; it's an explanation
to your fellow developer.

Documentation should tell you how the responsibilities are divided up in the
code. If you implement an interface, will you need to record metrics or will
that be handled for you?

Documentation should cover any processes you need to follow when making
certain kinds of changes. If you need to do something in two separate deploys,
those steps should be written down.

------
rglover
1\. Where is the data? How does it get from the user to the database (e.g.,
REST API, GraphQL, SOAP)?

2\. What specific technologies are in use (languages, frameworks, platforms,
third-party services, etc.)?

3\. How does configuration/security work? In other words, where are
keys/tokens floating around that I need to make sure don't get into the wrong
hands or misplaced?

4\. What are the best resources/references for the technologies in use?

In essence, what's the landscape and where are the "breakpoints" that could
wreak havoc for customers and the business?

------
cjfd
A high level overview.

First separate it out in what the different processes are that are running in
the working system. How are they communicating? What is their function? Why
was it separated in this particular way?

For the more difficult of these programs/processes: what is their rough
structure and what function does each part have? Why are they difficult? What
strategies were used to conquer this difficulty? What are the most common ways
in which they get extended?

How does the build work?

------
AgentOrange1234
I would wish the documentation fairy would give me a file of asserts that 1.
explain (in comments) the invariants the system is supposed to maintain and
check them, and 2. explain the protocols that modules communicate with and
check that they are being obeyed. And a fast test suite where these asserts
are checked.

~~~
jnxx
This is a very good point, too. Knowing the invariants is extremely important
for keeping the code correct when changing it, but, similar to locking and
concurrency patterns, they are often implicit and sometimes need to be
implemented in many place in the code.

------
jackcodes
Brevity. Assume your users are intermediate developers and only tell them what
they need to know.

The worst documentation I had to parse recently was react-beautiful-dnd, and
I’m saying this somewhat conservatively as it’s evident a lot of effort has
went into producing something comprehensive. But I was paralysed by the volume
of it, reams and reams of methodology and design decisions, how to contribute,
and the history of the project. In the end I had to use one of the community
codepen examples to get where I needed. Without meaning to stereotype too
heavily I see this mostly in junior friendly React projects where you have
more people contributing emojis to markdown than you have architecting your
APIs. In case anyone from react-beautiful-dnd/Atlassian reads this, you have
all the documentation you need, but make it less like a textbook and more like
a two page CV.

The best documentation I’ve seen is spider-gazelle (crystal). It’s the prefect
balance of plain-English explanation and example code. It probably helps that
is was architected and written by the same person, and they were able to
really hone down on exactly the right information to transfer.

Edit; I’ve just realised that your specific example is for an internal
enterprise project, rather than a public facing library so the variables you
optimise change slightly. I’d be maintaining and developing this software as a
contributor, and the documentation is specifically for on-boarding me. I’d
want to see more of the architecture rationale, point-in-time thought process,
and explanations of business constraints that led to certain decisions being
made (e.g. what prevented optimal architecture first time around)

~~~
jnxx
> Brevity. Assume your users are intermediate developers and only tell them
> what they need to know.

Sorry for an interjection. The documentation I am having in mind is technical
documentation for future developers of a code base (its implementation). Not
users of the API a code base.

Also, it would be possible to document the wrong stuff or stuff that people
really already know, but it is basically not possible to document _too much_ ,
because of the time constraint.

~~~
jackcodes
Apologies for this, I’ve clarified this in my edit. I’d realised immediately
after I’d submitted that it’s for a different purpose. Hope the edit clears it
up a bit more.

~~~
jnxx
Brevity is clearly an important quality aspect for all writing. But it does
not come for free. For many people, writing concise documents is rather time-
consuming, and there are certainly cases where you'd rather want to have a
document at all, even if it is painfully bloated, than nothing.

~~~
jackcodes
I agree, and one of the examples is your use case - undocumented enterprise
software. To go back to the title, brevity makes the documentation good, but
I’d rather have bloated in-date documentation than no documentation.

------
baitman
For internal docs, just like external (user-facing) ones, the key is for them
to be focused around what the user needs. In this case, that means things
like:

\- overall architecture of the system, what lives where

\- how it's meant to work, what the main interfaces to users are, and what
users expect from them

\- common tasks and troubleshooting, eg stuff that often goes wrong

One of the major problems with internal docs is keeping them up to date. So
that brings the second key point which is minimalism: don't document
everything. Stick to what is genuinely relevant and useful to developers on
your project. It's a hard balance to find, but you have to be practical and
recognise that if you write something you can't commit to maintaining, it may
not be worth writing at all. (it's still hard with user-facing docs, but at
you have releases which you can use as a drive/reminder to update things)

Thirdly, structure really matters. If people can't find things in your docs
then they become much less useful. Good information architecture is hard,
though. I'm a tech writer and I honestly believe that most engineers can write
decent docs, given a bit of training (eg I've given something like this and
people have found it useful
[https://youtu.be/8TD-20Mb_7M](https://youtu.be/8TD-20Mb_7M)) - but working
out a clear structure is something that it helps to talk to someone with
practise about. If that's not possible, look at products similar to yours and
see what their high-level structure is - if it looks good, do something
similar, and if it doesn't, that gives you something to avoid.

------
arkadiytehgraet
Discoverability is at least as important as the documentation content itself.

A lot of really good advice here is given with regards to the content.
Obviously, this is very important; however, it is not enough, when there are
multiple places of documentation. Keeping at most 2 (code + wiki or something)
sources is essential to ensuring that docs are actually read and can be found
by others.

In my current company (~3k developers) there are more than 10 different places
for documentation. This both makes it difficult to find anything AND
discourages developers to write any docs in the first place.

------
ka0lin
\- Which problem will be solved by the software \- What is the system's
context \- How to Build \- How to Run

The rest is in the code. And 80% of all »projects« lack at least one of the
points above.

~~~
jnxx
> The rest is in the code.

I know that philosophy well, but I do not really agree with it - not at all.
For example in concurrent code written in C, the way things are synchronized
is normally implicit. You can understand it if you read _all_ of the code, but
not by looking at single functions. If you add accesses without proper
synchronization, you will get quickly undefined behaviour which can cause
extremely nasty concurrency bugs.

I also agree with the several comments made that it is often more helpful
"why" something is done, than "how". This is, of course, valid for in-code
comments as well, but IMO equally important in overview documentation.

> And 80% of all »projects« lack at least one of the points above.

Yeah, I know. In fact, I have rarely seen good technical documentation.

------
uberswe
Start with any inventions or algorithms that make the software unique, make
sure these are documented. After that I would focus on the highest level,
document the input handlers, views or maybe controllers. This will give a good
overview of the application and cover the most complicated things. If the
developer has more time left to document they simply try to go deeper and
deeper (more detailed).

~~~
jnxx
Good points. For really complex algorithms, I have a high opinion of literate
programming.

For more contextual stuff, like, for example, build procedures, I am wondering
whether using a Wiki would be better. It is not only easier to keep it up to
date, but it also allows to cross-link topics and this in turn makes it easier
to split up information into smaller, easier to find and more digestible
units.

Of course, normally a Wiki must be maintained and organized, otherwise it
becomes a steaming mess, but if it is a focused effort to write a dozen pages
which document a specific area, this is not hard do organize reasonable.

------
wirthjason
I work at a bank writing financial software —- a trade capture system, it’s
basically everything that happens after the client agrees on the price.

Knowing the business and thus rules is the most important thing.

We support a global business and Asia regulations are different from Europe,
products are managed differently by different traders, etc.

Knowing the business gives context to what the software is doing and why
because this kind of software is written by people who didn’t understand the
rules in the first place. It isn’t abstracted correctly and there is a ton of
if-else branching for edge cases, variable/function/class naming that is
inconsistent and often incorrect, etc.

I would also +1 a known bug list. You can spend a lot of time tracking down a
“bug” that seems new because it’s an edge case that rarely appears. Each time
it comes up the users think it’s new and a complain.

------
majkinetor
The key is to be

\- up to date

\- contextual

\- progressive

\- easily accessible and updatable

\- most be in CI/CD pipeline with builds and tests

All those might seem simple, but in practice are hard to achieve.

Achievable in single month is unrealistic requirement. Documentation is
ongoing process, evolves with the code - its as unrealistic as getting good
software in a month.

~~~
jnxx
> Achievable in single month is unrealistic requirement. Documentation is
> ongoing process, evolves with the code - its as unrealistic as getting good
> software in a month.

I know. I ask what can be done realistically in the given time.

------
tzm
Bryan Helmig (CTO Zapier) gave an excellent presentation on this back in 2012
at a conf, then wrote a blog post. I highly recommend reading it.

Post:
[https://web.archive.org/web/20130629000255/http://bryanhelmi...](https://web.archive.org/web/20130629000255/http://bryanhelmig.com/your-
api-consumers-arent-who-you-think-they-are)

Slides: [https://www.slideshare.net/bryanhelmig/your-api-consumers-
ar...](https://www.slideshare.net/bryanhelmig/your-api-consumers-arent-who-
you-think-they-are)

------
s_kilk
In those constrained circumstances, what I want most is a high level explainer
of what the system is supposed to do, how it does it, and any relevant
background information on why it does its thing in this particular way.

"this service sits between x and y, doing z. Z is handled by libraries a and
b. We couldn't use c because reason d. This is how you call it, and this is an
example result. You'll notice that we're passing both the user id and email
address in the request, because we didn't want this service to talk to the
database. Oh also this whole thing depends on a local sqlite cache because
shrug"

------
macando
Following The First Tenet of Domain Driven Design: Ubiquitous Language.

"Evans makes clear that using the ubiquitous language in conversations with
domain experts is an important part of testing it, and hence the domain model.
He also stresses that the language (and model) should evolve as the team's
understanding of the domain grows."

Simply, all team members should be on the same page and have a clear
understanding of the underlying (and evolving) domain model.

[https://martinfowler.com/bliki/UbiquitousLanguage.html](https://martinfowler.com/bliki/UbiquitousLanguage.html)

------
tabtab
What I prefer is a relatively small written document to give an overview of
the application/system, common usage scenarios, and big caveats or tricky
spots.

Edge cases and smaller design decisions on the other hand should go into a
kind of wiki and/or bug database that is searchable based on entity(s),
issue/feature type, programmer, commentator (content author), change
requester, etc. There will often be back-and-forth discussions that would
bloat up a formal document. But to be useful, it requires a good knowledge-
base, both product-wise and management-wise.

------
squarefoot
As others wrote, examples, examples, examples. And ask for code to be
thoroughly commented. And data! Each variable, each constant, sizes, limits,
caveats, traps etc. must tell you what they do and why: you aren't just
getting the working code, you are getting also the bugs, minus the
subconscious inhibitions that prevented the old developers from making them
appear. Learning what the code does will be hard by itself, but debugging
without proper documentation can become a nightmare.

------
jbverschoor
Proper architecture

Remove the unneeded layers

Use of standardized frameworks

Proper datamodels

Proper naming

Proper error handling or no handling at all

A few diagrams

What to tell the manager.. maybe that he should’ve been more involved in the
overall quality of the product and motivation of his team

~~~
jnxx
That sounds more than can be done in a month. I don't think this wish would
make the fairy happy.

------
GuB-42
The documentation would describe how to go from a recently formatted computer,
the source code of the project and a list of off the shelf software with the
necessary licences to the final product in a ready to ship and run condition.

If internal servers are involved, the way to setup these servers from scratch
should be included too.

Now that I have all the parts, I can deal with the rest.

------
veritas3241
I quite like this framework from Divio[0] for thinking about how to write
documentation. It mainly gets you thinking about the _purpose_ of your
documentation (and therefore the audience).

[0]
[https://www.divio.com/blog/documentation/](https://www.divio.com/blog/documentation/)

------
tyleo
I’m going to relate an experience rather than answer your question. I don’t
think the question is in its best form because it can be time consuming to
write proper documentation. The existence of the “fairy godmother” takes time
out of the equation which is an important variable.

I used to work at Microsoft on a team with poor documentation. By my reckoning
developers writing code would have preferred better documentation while
developer managers couldn’t justify the time to write it. Both preferences
were sensible.

From the implementer perspective you could get caught up on a problem for
several hours before having a conversation with another developer who could
unblock you instantly. If the content of that conversation had existed in some
document it could have been searched and several hours could have been saved.

From the managers perspective, product requirements and features changed so
rapidly that a few days spent writing documentation could easily create a
document that no one would use. Indeed, this was the case in a few
experiments.

I lead a team for awhile and we hit the first problem a lot. However, I
noticed that most of the conversations which unblocked my team had happened
over email (I was CC’d). The tone of emails did not make for perfect
documentation but they were helping my team so they were better than nothing.
I decided to start taking some of the emails and pasting them into a OneNote
document. After a few months the result was a large collection of imperfect
documentation created very economically.

The OneNote document was wildly successful:

* Because the notes were from emails which had at least unblocked one member of my team, they had proven value.

* Because developers were already writing emails there was low cost to pasting them in OneNote.

* Developers could also correct the OneNotes and everyone would get the changes unlike an email thread which was only accessible to people on the to and cc field.

I also believe that the imperfections and limited editing features of email
made it easier for people to write these documents: they didn’t feel like the
documents needed to be well-formatted or perfectly written, if someone had
something to say they had unlimited license to paste it in the document.

So thats been my experience and I will bet on it again in the future. The only
caveat is that I worked on games which is the cause of the rapidly changing
requirements. “Unfun” features could entirely be cut and we essentially
rebuilt the product every few years to release a new game obsoleting much of
the documentation. This sort of thing may not work for a public facing API for
example.

~~~
jnxx
> The existence of the “fairy godmother” takes time out of the equation which
> is an important variable.

I know that good documentation takes time.

What you write about OneNote is interesting. The only caveat is that using
Microsoft Windows would be extremely unproductive in this environment (it is
embedded software which needs to run on a Linux platform, so using Windows for
documentation creates _a lot_ of additional friction).

I think this basically has the features of a Wiki in which you could insert
emails and other help information, and whose organization can be ordered and
evolved over time.

Do you have any experience with [Zim Wiki]([https://zim-
wiki.org/](https://zim-wiki.org/)) (a Desktop Wiki software) or Docuwiki
(which is tailored especially for documentation) ? I've used the former quite
successful for personal information management (it is free software, with free
as in "free speech", and it even runs under Windows). What I like especially
about it is that it can be integrated really easy into version control with
git, or use the existing git version control of the corresponding code.

At some points in my past, I've also used
[Dokuwiki]([https://www.dokuwiki.org/dokuwiki](https://www.dokuwiki.org/dokuwiki))
very, very successfully as member of a group. For other environments, wikis do
not seem to work so well - I am still struggling to understand what makes the
difference.

~~~
tonyarkles
I am a Linux guy through and through, but I have an old Surface 3 that I take
to meetings and coffee shops. The web version of OneNote (via Office 365)
works awesome for reading OneNote notebooks and for writing typed text. From
the Surface I'll usually use the pen and then type up a summary later. Search
on my messy handwriting usually works pretty well too.

~~~
jnxx
What I remember, don't have the surface notebooks serious problems with both
built quality and Linux power saving?

Personally, I've zoomed in on Thinkpads, old business models. They are
sometimes a bit bulky, but rugged. They don't break and can be upgraded and
repaired well. The old ones have really good keyboards which is important for
me as a console user. And they have usually out-of-the box good driver
support. And that's something I am expecting today. 20 Years ago, I tolerated
a lot of driver problems, as I was a poor student and Linux driver support was
often patchy. Today, I expect that it just works. And last, given Microsoft's
history with Nokia, Maemo, and the N9, I would not expect any reliable Linux
hardware support from Microsoft (Fool me twice, shame on me).

------
jimmyvalmer
Documentation becomes superfluous at the limit since eventually you'll have to
read the code.

With this in mind, I echo earlier sentiments of brevity, REPL-friendly
examples, and empathy, but above all BREVITY since greater detail is either
outdated or as cognitively demanding as reading the actual code.

------
um304
Assume your audience is highly intelligent but knows little about the subject
you're writing about.

------
RickJWagner
The absolute key to good technical documentation is to have a writer that
understands the software.

Lacking that, good documentation is impossible.

With that, good documentation is possible, but still requires a lot of other
things (like a well-designed doc framework, good writing style, etc.)

------
jonas_kgomo
Google launched a project this year called Season Of Docs, match-making
technical documentation with open source projects. What could be interesting
is offering Technical Documentation as a Service (TDaaS)

------
AlexTWithBeard
I wish for a person who understands the thing to still be around.

Most of documentation I've met in my career is either outdated incomplete or
often both at the same time.

------
BerislavLopac
Good documentation has the intended user in mind, with the examples, basic
tutorials and references that will show the intended user how to use the
software.

------
welcome_dragon
If the documentation has any code snippets, they absolutely should have unit
tests around them to ensure the documentation stays current with the code

------
wly_cdgr
I would ask the documentation fairy to decompose the code in a way that
obviates the need for external documentation.

------
samogon
If a distant person can solve the problem with the help of the instructions,
then this is probably the key to success.

------
dredmorbius
The worst documentation -- typical of virtually all consumer devices and
software -- simply runs through menus (or commands, funtions, features, etc.)
and repeats to you, often in the same words, menu options, without telling
_how_ or _why_ or _when_ features apply. Very frequently units are omitted as
well.

"The frobinator txl parameter sets the frobinator txl". What is the
frobinator? What is the TXL? What are the units? Seconds, tenths, mills, nano,
minutes, hours, days?

Good docs:

\- Explain _why_ and not just _what_ or _how_.

\- Give an overview of the tool or system. Technology is a means to an end.
Describe the ends and the means.

\- Describes the components. What are the parts of the system? How do they
relate to one another, and the problem domains?

\- For quantities, specify units. Integer, float, signed, degree, etc.
Physical units if appropriate.

\- Give a quick-start guide. If I just want to get up-and-running, what do I
need?

\- Give a detailed walkthrough of getting up and running. What parts and steps
are needed? _What prerequisites are required before starting?_

\- Intended audience.

\- Operating parameters. Minimum requirements. Maximum capacity. SLAs if
appropriate. Service tiers, if appropriate.

\- Practical examples and recipes. _Unix Power Tools_ by O'Reilly & Associates
is nearly a quarter century old, but remains an excellent book for getting
"over the hump" in understanding the 'Nix commandline environment.
Interestingly, its GUI companion, _X11 Power Tools_ was vastly less suited.

\- Task-and-domain oriented, rather than component-and-function oriented. We
have problems, and apply tools to them. Very few people pick up a tool and
look for a problem that fits it (at least to a first order). Evi Nemeth's Unix
Administration books are excellent in this regard.

\- Examples. Useful recipies (as noted above).

\- Danger zones. Places to watch out for.

\- External references. No, you _don 't_ need to include Yet Another Bash
Programming guide, or yet another <your language here> guide. Refer to a good
third-party reference. Even if your company / publisher didn't produce it
(O'Reilly used to be really good at this).

\- Differentiate between basic, advanced, and debug modes. Most technologies
have basic operators, advanced operators, maintenance, construction, and
architect roles associated with them, in rough order. (Some might argue that
mainenance is harder than construction and architecture.) Basic operators need
the least information and access, architects and integrators need more.

\- Distinguish _internal_ and _external_ interfaces. These generally fit
different roles.

\- Performance tuning, if appropriate.

Regards mgt. wanting stuff up-and-running and people being impatient: those
are bad signs of high technical debt. That gets repaid one way or another, and
it's usually not pretty.

------
joelx
Documentation should be created as you go... Not before and not after.

~~~
jnxx
I agree that this is ideal. But it is hard to push through in today's
environment where long-term quality aspects are so often set aside.

------
julienreszka
Lots of examples for the same function, variations of those examples.

------
eterps
Automated checks to guarantee that it is always up to date.

------
ykevinator
Examples and empathy.

------
snitzr
Active voice.

------
british_india
If the system you are facing is object oriented, then the traditional flow-
chart is a bad match. Still, you need to create a map of how the entire system
works. Learning to do that is the single greatest predictor of your success.

------
rb808
[https://agilemanifesto.org/](https://agilemanifesto.org/)

> Working software over comprehensive documentation

If your application is so complicated it needs documentation to understanding
it, there is a problem with the way the application is structured. In the
magic month I'd get the application broken down into independent parts which
can be developed and tested separately.

~~~
ctraynor
> while there is value in the items on the right, we value the items on the
> left more

The agile manifesto doesn't say that you shouldn't write documentation. That's
an incredibly damaging idea.

