
Ask HN: How to write techincal documentation for complex systems? - kcindric
I&#x27;m a junior dev in a large company and after a few small projects I got an assignment to write a technical document for the system my team develops and supports. The document will then be used internally between developers, especially newcomers.<p>The system is made of out of the box enterprise solutions, custom software, a bunch of APIs, numerous SQL and server instances, legacy business code, web apps etc. There are bits and pieces of documentation for some of the parts but there is no complete document where all of the ins and outs of the system are explained in a readable and understandable way.<p>I&#x27;ll have help from senior devs and architects but this is mainly my task. Are there any articles, tutorials, books to read and can you give me advice how to start, what to look for and what to avoid before I jump into this rabbit hole?
======
TXV
I write a lot of documentation. I do it not because others ask, but because I
genuinely believe it is going to be helpful to someone at some point, and
anticipate this need. So when Bobby from marketing asks about a feature, or
Kate the junior dev can’t wrap her head about some algorithm, hey, I got them
covered!

So I think this mindset is the first thing you need in order to get going. It
will inspire you to write more and better.

Secondly, my practical advice is the following: divide your doc in sections.
Plan them out beforehand by writing just titles and subtitles. See how they
fit together, if their sequence makes sense. Rearrange them until they convey
a clear story. Usually you might want to have three macro-sections: 1.
Introduction - what is the document about, who is it indended for, and why it
was developed. This helps set expectations right off the bat. You can also
describe the big-picture goals of the system/feature. What is it used for.
What are the main use cases. 2\. System/Feature Overview: here you can
describe the big-boxes architecture, the main components (apps, servers,
middleware, db, whatever), what they do, and how they work together. Describe
communication protocols and standards followed. Describe functionalities the
system provides. You can follow up on the use cases you mentioned in part 1
and show how the system delivers them. 3\. Technical Details/Implementation
Choices: depending on the audience of your doc, you might want to document
non-obvious design choices. This is also where might want to describe expected
inputs and outputs. If it’s an API, describe the routes, accepted methods,
paylods. Provide actual examples, as many as you can. Describe the data model.

Then as you follow this trace, you might find out you wrote a lot about a
certain topic. Depending on the level of detail you want to achieve, break it
down in smaller sub-sections, or move parts over to section 3.

As for the writing style, you might want a prose with short sentences and easy
language. Make sure to explain stuff thoroughly and not take anything for
granted. Everything that looks damn obvious today, won’t be 6 months from now.

Sorry if this looks like a stream-of-consciousness. It sort of is. I hope you
can find some of it useful.

~~~
kcindric
It's a rather structured stream-of-consciousness, thanks. I'm mainly afraid
that because I really don't know what are the parts of our system and what
they actually do that I'll screw this up. But I really trust my support system
of senior devs and PMs and with my beginner mind this could be a great
learning experience.

------
jonjacky
These two old threads from Ask Metafilter might be pertinent:

[https://ask.metafilter.com/98291/How-does-IT-documenation-
wo...](https://ask.metafilter.com/98291/How-does-IT-documenation-work) (2008)

[https://ask.metafilter.com/111250/Document](https://ask.metafilter.com/111250/Document)
(2009)

------
cenderme
Did you try LaTeX?

