Ask HN: What is the technical document format that you use?

6 points·wizardofmysore··5 comments

I am gathering the best practices around technical documentation.

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?

View on HN

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.

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

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?

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.

Markdown for docs, MonoDraw for diagrams.

Reply on news.ycombinator.com