
Ask HN: What is the technical document format that you use? - wizardofmysore
I am gathering the best practices around technical documentation.<p>What is the format that you use?
How do you keep them updated?
What tools do you use to write the document?
What diagrams are a part of it?
======
CyberFonic
In our work, all the technical documents are published on our intranet site.
We discourage printed documentation as it can quickly get out of date and
under pressure people have been known to use the wrong documents and make the
problem they are trying to solve worse. Of course, you can always print from
website if heading into a secure data centre where external access is locked
down and unvetted notebooks are not permitted.

Most of the documents are created in MarkDown and the web pages are updated
using Makefiles. Diagrams are preferably in GraphViz, compiled to PNGs and
included as images. When GraphViz is unsuitable, LibreOffice draw and export
as PNGs.

We also take high-res photos of equipment layouts, etc, annotate them with
GIMP and include the exported JPGs.

------
throwaway413
I like to use Markdown for docs, and Vue for frontends, so VuePress
([https://vuepress.vuejs.org/](https://vuepress.vuejs.org/)) does a great job
checking off a bunch of functionality I want out of the box.

------
rman666
That’s a big set of questions! But let’s start with the obvious: Microsoft
Word - PDF files - Plain Text - HTML - Various Wikis. But how does this
obvious response help anyone? What are you trying to accomplish?

~~~
wizardofmysore
As mentioned "I am gathering the best practices around technical
documentation.".

This is for my tech company and we are looking towards improving the way we do
documentation.

------
ezekg
Markdown for docs, MonoDraw for diagrams.

