Ask HN: How does your team write documentation? What tools do you use?

I really like these &quot;how do other people do X?&quot; questions on HN. Thanks for asking it!<p>I work at a small startup with a roughly 10-person eng team.<p>When we write docs we focus mainly on architecture and processes. The architecture docs often emerge from a &quot;tech spec&quot; that was written for the development of a feature that required a new service, or substantial changes to a new one. We keep everything in Github, in a README or other markdown files.<p>We also write API docs for HTTP endpoints. These are written with client developers and their concerns in mind. When doing this for a Rails app we use rspec_API_documentation, which is nice, but it can be annoying to have testing and documentation so tightly couples. We&#x27;ve talked about changing how we do this, but we always have more pressing things to do.<p>We never write docs for classes or modules within an app&#x2F;service.

All of our docs a written in Markdown in a git repo [1]. That then gets built with a custom static site generator that I wrote [2]. Finally the output gets pushed back to gh for hosting on gh-pages [3].<p>I&#x27;m actually pretty proud of the search that I put together for this setup too, it&#x27;s all done in the browser and the indexes are built at compile time which is then downloaded in full for a search, which sounds silly, but it works surprisingly well [4].<p>[1] <a href="https:&#x2F;&#x2F;github.com&#x2F;exosite&#x2F;docs&#x2F;" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;exosite&#x2F;docs&#x2F;</a><p>[2] <a href="https:&#x2F;&#x2F;github.com&#x2F;exosite&#x2F;docs&#x2F;blob&#x2F;master&#x2F;gulpfile.js" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;exosite&#x2F;docs&#x2F;blob&#x2F;master&#x2F;gulpfile.js</a><p>[3] <a href="http:&#x2F;&#x2F;docs.exosite.com" rel="nofollow">http:&#x2F;&#x2F;docs.exosite.com</a><p>[4] <a href="http:&#x2F;&#x2F;docs.exosite.com&#x2F;search.html?q=subscribe" rel="nofollow">http:&#x2F;&#x2F;docs.exosite.com&#x2F;search.html?q=subscribe</a>

We use flatdoc and Swagger UI for building docs, like: <a href="https:&#x2F;&#x2F;open.coding.net" rel="nofollow">https:&#x2F;&#x2F;open.coding.net</a><p>flatdoc is a small JavaScript file that fetches Markdown files and renders them as full pages: <a href="https:&#x2F;&#x2F;github.com&#x2F;rstacruz&#x2F;flatdoc" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;rstacruz&#x2F;flatdoc</a><p>Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. <a href="http:&#x2F;&#x2F;swagger.io" rel="nofollow">http:&#x2F;&#x2F;swagger.io</a>

Word docs converted into PDF for manuals. Some other are hand-crafted Photoshop tables&#x2F;text&#x2F;graphics to create PDF. Sad, sad stuff, IMHO.<p>Trying to get people onto Sphinx [0], and use it for some non-sanctioned documentation with good success, but unlikely to make it official.<p>I really think version control is important: what changed, who changed it, provisional changes through branches, and removing the bottleneck of &quot;I updated the docs, please everyone check before release and send me your comments&quot;. It should be patches, and only patches.<p>[0]: <a href="http:&#x2F;&#x2F;sphinx-doc.org&#x2F;" rel="nofollow">http:&#x2F;&#x2F;sphinx-doc.org&#x2F;</a>

Because I was not happy with the existing stuff, I&#x27;ve built an opensource project for creating technical online documentations some time ago, named &quot;docEngine&quot;. My goals were:<p>- Easy editing (namely markdown files in folders) - Runs on &quot;cheap&quot; hosting&#x2F;everywhere (built with PHP) - Supports multiple languages (so you can create docs in english, german, etc.) - Can have editable try-on-your-own demos embedded into the documentation - SEO friendly (clean URLs and navigation structure) - Themeable (themes are separated and run with the Twig templating engine) - Works on mobiles out of the box - Supports Plugins&#x2F;Modules for custom content&#x2F;behaviour - Formats reference pages for objects&#x2F;classes&#x2F;APIs in a nice way - Supports easy embedding of disqus for user feedback - Other stuff I forgot right now<p>The system powers the knowledge base of my recent app &quot;InSite&quot; for web developers: <a href="https:&#x2F;&#x2F;www.insite-feedback.com&#x2F;en&#x2F;help" rel="nofollow">https:&#x2F;&#x2F;www.insite-feedback.com&#x2F;en&#x2F;help</a><p>You can see it also in action working - with a different theme - for my javascript UI library &quot;modoJS&quot;: <a href="http:&#x2F;&#x2F;docs.modojs.com" rel="nofollow">http:&#x2F;&#x2F;docs.modojs.com</a><p>That page is a bit more complex. It does _not_ use multiple languages there but it makes great use of the reference pages and has many many editable live-demos. It also has some custom modules like a live build script for the javascript library. At one point it even had a complete user-module with payments but I disabled that when modoJS went opensource.<p>Another instance of docEngine runs for my pet html5 game engine: <a href="http:&#x2F;&#x2F;wearekiss.com&#x2F;gamekit" rel="nofollow">http:&#x2F;&#x2F;wearekiss.com&#x2F;gamekit</a> This one uses the default theme, has most pages in two languages and again incorporates a couple of live demos.<p>I host a little documentation about the engine itself here, but its not complete right now: <a href="http:&#x2F;&#x2F;wearekiss.com&#x2F;docEngine" rel="nofollow">http:&#x2F;&#x2F;wearekiss.com&#x2F;docEngine</a> You can also find the github link to the project in the footer of every hosted documentation.<p>Have fun with it - I give it away for free. Critics and comments welcome! Everything I have linked was built by myself.

Trying something new on this month&#x27;s project: &quot;developer first experience&quot;.<p>Besides the README.md to get started, the app defaults to a private portal with a component playground (for React), internal docs (for answering &quot;how do I&quot;), and tools for completely removing the need for doc pages at all.<p>I believe that documentation has to be part of the workflow, so component documentation should be visible while working on the component, tools for workflow should have introductions and helpful hints rather than being just forms and buttons, etc.<p>So far, this is proving fruitful.<p>(Side note: wikis are where docs go to die.)

The first software system that I worked on was the operator consoles for a nuclear power plant. A two year long dev project. We used Framemaker (1990, before Adobe purchased them). Was an awesome tool for technical documentation. Our documentation when printed and bound was three feet wide on a shelf. I think I contributed two inches. It&#x27;s been all downhill since - both in terms of the tools and the quality of the documentation. Now days it&#x27;s the typical - auto-gen from code plus markdown for narrative.

Long ago I learned to love wikis. Mediawiki, Dokuwiki (easy to set up), or Confluence. Hardest part is to keep people from just throwing garbage everywhere--if that happens, people stop referring to the docs, and the system collapses.<p>The important thing about docs is to keep in mind the audience. This is important because it lets you estimate their mental model and omit things that are redundant: for example, if it&#x27;s internal documentation for a codebase, there is little need to explicitly list out Doxygen or JSDoc style information, because they have access to the damned source code. External audiences may need certain terms clarified, or some things explained more carefully because they <i>can&#x27;t</i> just read the source.<p>I&#x27;d say that the biggest thing missing in the documentation efforts I&#x27;ve seen fail is the lack of explanation for the overarching vision&#x2F;cohesive architecture of the work. This is sometimes because there <i>isn&#x27;t</i> a single vision, or because the person who has the vision gets distracted snarfing on details that are not helpful without a preexisting schema to hang them on when learning. So, always always always have a high-level document that describes the general engineering problem the project solves, the main business constraints on that solution, and a rough sketch of how the problem is solved.<p>Ideally, the loss of the codebase should be less of a setback than the loss of the doc.<p>I will say that, as your documentation improves, you will hate your project more and more--this is the nature of the beast as you drag yourself through the broken shards of your teams engineering.

I enjoy Literate CoffeeScript and that&#x27;s where I picked up the concept of Literate coding.<p>I believe that literate style of code writing has many benefits in any language.<p>Basically mix markdown with the codebase and export the documentation from the same file.<p>For a very well executed and interactive example check out<p><a href="http:&#x2F;&#x2F;dave.kinkead.com.au&#x2F;modelling-the-boundary-problem&#x2F;" rel="nofollow">http:&#x2F;&#x2F;dave.kinkead.com.au&#x2F;modelling-the-boundary-problem&#x2F;</a>

Our APIs are documented with comments that Sphinx uses to generate HTML documents. Unfortunately, all of our other documentation is written in Microsoft products because &quot;that&#x27;s what people use&quot;

Sphinx or mkdocs:<p><a href="http:&#x2F;&#x2F;www.sphinx-doc.org&#x2F;en&#x2F;latest&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.sphinx-doc.org&#x2F;en&#x2F;latest&#x2F;</a><p><a href="http:&#x2F;&#x2F;www.mkdocs.org&#x2F;" rel="nofollow">http:&#x2F;&#x2F;www.mkdocs.org&#x2F;</a><p>Which make it easy to create html, pdf, epub, latex formats, etc.<p>I like to create a user guide, developer guide, and ops guide for each large project.

We have technical writers who work in conjunction with developers to author the documentation. I don&#x27;t know what tool they use. However, since you say you want to get better at writing docs, let me offer some perspectives based on a user of documentation.<p>1) Write to all of your target audience. For example if your product is targeted at both technical and non-technical people, then write the documentation in such a way that non-technical folks can understand it. Don&#x27;t just write for the technical people.<p>2) If possible, write documentation around several &#x27;how do I do XYZ task&#x27;? My experience has been that people tend to turn to documentation when they want to execute a specific task and they tend to search for those phrases<p>3) As much as is possible, include examples. This tends to remove ambiguities.

We use Swagger specification (automatically generated using annotations in Java) and generate Slate documentation from Swagger specification for API documentation. (<a href="https:&#x2F;&#x2F;api.rakam.io&#x2F;" rel="nofollow">https:&#x2F;&#x2F;api.rakam.io&#x2F;</a>). We also use markdown for generic (tutorials, technical etc.) documentation and render the markdown files fetched from Github in documentation page using JS. Since everything is dynamic, we don&#x27;t need to worry about updating the documentation page, we just update README files of repositories, add documents to our documentation repository and the documentation page is always up-to-date. (<a href="https:&#x2F;&#x2F;rakam.io&#x2F;doc&#x2F;" rel="nofollow">https:&#x2F;&#x2F;rakam.io&#x2F;doc&#x2F;</a>).

Elixir has a <i></i>great<i></i> documentation system built in. I use that.

At Ionic, we use Dgeni (<a href="https:&#x2F;&#x2F;github.com&#x2F;angular&#x2F;dgeni" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;angular&#x2F;dgeni</a>) for API docs. We have a few custom build tasks that allow us to version the API docs.<p>We also have higher level documentation, which is meant to serve as a sort of conceptual overview of the framework, as well as to show what the framework comes with out of the box. This section is written mostly in kramdown, which gets parsed by jekyll before it&#x27;s turned into HTML.

Most of our documentation attention goes towards the user manual and the system operator manual.<p>We generate the bulk of those manuals based on our object model, which is liberally sprinkled with (text only) descriptions. We&#x27;ve created a simple XML-based authoring framework which allows us to create pretty tidy documentation. Including images, tables, code examples etc.<p>We convert that XML to Apache FOP. At the end of the process, we&#x27;re left with a bunch of tidy PDF manuals in a variety of languages.

The thing that has always guided me right is that you need to a) split up functions, b) document method headers in every case with a short description of what it does, and finally c) come back one month later and rewrite any documentation that does not make sense.<p>This is the most important step. If you cannot remember it from a blank slate, then no one can. Keep doing that until you understand the code at first glance. Then your code will be easy for anyone to maintain.

A mardown-based wiki under version control and code comments. Everything else likely isn&#x27;t worth docummenting or just merits direct person-to-person communication.

LaTeX. We have academic roots, it works with source control, and the output looks fantastico.

At work, I&#x27;ve seen a variety of solutions, depending on the teams I work with:<p>* MS doc(x) on a network folder with an excel spreadsheet to keep track of docs (and a lot of ugly macros).<p>* MS doc(x) in a badly organized subversion repository (side note here, docs comments and revision mode are heavily used in those contexts, which is really annoying)<p>* rst + sphinx documentation in a repository to generate various outputs (html, odt, pdf...) depending on the client.<p>In some cases we also use Mako (a python template engin) before sphinx to instantiate the documentation for a specific platform (ex: Windows, RedHat, Debian...), with just a few &quot;if&quot; conditions (sphinx could do it in theory, but it&#x27;s quite buggy and limited).<p>I&#x27;ve also put in place a continuous build system (just an ugly shell script) rebuilding the sphinx html version every commit (it&#x27;s our &quot;badly implemented readthedocs.org&quot;, but it&#x27;s good enough for our needs).<p>In other cases we use specification tools like PowerAMC or Eclipse&#x2F;EMF&#x2F;CDO based solutions, the specification tool in that case works on a model, and can generate various outputs (docx, pdf, rtf, html...).<p>At home, for my personal projects, I use rst + sphinx + readthedocs, or if the documentation is simple, just a simple README.md at the root of my repository.<p>As a personal opinion, I like to keep the documentation close to the code, but not too close.<p>For example, I find it really annoying when the sole documentation is doxygene (or equivalent), it&#x27;s necessary to document each public methods&#x2F;attributes individually, but it&#x27;s not sufficient, you need to have a &quot;bigger picture documentation&quot; on how stuff works together (software and system architecture) in most cases.<p>On the other side, keeping the documentation away from the code (in a wiki or worst) doesn&#x27;t work that well either, it&#x27;s nearly a guaranty that documentation will be out of date soon, if it&#x27;s not already the case.<p>I found having a doc directory in the source code repository a nice middle ground.<p>I found wikis annoying in most cases, rarely up to date, badly organized and difficult to version coherently and properly (ex: having version of the doc matching the software version).

This question is on my mind too. My clients documentations are usually a mix of MS Word &amp; Visio. Lots of repetition and gunk in between.<p>Ideally, I&#x27;d love to find a mechanism that:<p><pre><code> - provides the OO principles in documents; Encapsulations, Abstraction, Polymorphism, Inheritance . - Accessible &amp; maintainable by non-techies. - Allows scripting (I toyed with PlantUML, but it was a bit rigid).</code></pre>

Not on a team, but I used mkdocs for this tutorial I built, then added a comment system that I built with react.js : <a href="https:&#x2F;&#x2F;amfarrell.com&#x2F;saltstack-from-scratch&#x2F;" rel="nofollow">https:&#x2F;&#x2F;amfarrell.com&#x2F;saltstack-from-scratch&#x2F;</a> The advantage of mkdocs is that it is markdown-based so it is super easy to get started.

Gitbook for Technical Documents, Google Drive for everything else.

We write the docs as markdown files and then use Doxygen to compile it to html and LaTeX for the traditional folks who MUST have a printable document. The markdown files are tracked on Git so that we can collaborate and track easily.

Bitbucket&#x27;s wiki on our project page (6-person startup). We document mostly application behaviour for technical users of the app (server team, content writers) and a little bit of architecture if the complexity warrants it.

I work at a very large company so you won&#x27;t be surprised to hear we use a variety of tools and there&#x27;s often overlap. Almost everything goes to Confluence (our program wiki) including tech specs and marketing documentation. The product team often uses something simple, such as Quip to store and collaborate on their docs. Marketing tends to migrate toward Drive. I think the best advice I can offer is to keep one &quot;source of truth&quot;. This isn&#x27;t too difficult when your team is small but as you start to grow, having one place devs, marketing, sales can go really helps streamline things.

The Texinfo format, using the in-Emacs Info browser. Yes, it means you only read your documentation inside Emacs, but it&#x27;s hands-down the best doc-browsing experience I&#x27;ve ever had. Hell to write, butter to read.

Shameless plug: I&#x27;m working on a documentation solution for dev teams. You can sign up for the beta at <a href="http:&#x2F;&#x2F;docily.com&#x2F;" rel="nofollow">http:&#x2F;&#x2F;docily.com&#x2F;</a>

We tend to thoroughly document our API (which is the backend behind our mobile apps and website) using ApiDocJs.com or Swagger.io&#x2F;swagger-ui Every service and method is thoroughly explained in detail so the front-end folks have a reference to work off of.<p>The rest of the systems are documented ad-hoc. Some readme files here and there, a large block of comments inside of confusing files, the occasional style guide, etc.<p>We also have an onboarding guide for new devs (just a PDF) which walks them through our systems, our tools, etc. Nothing fancy, about 10 pages.

This is a problem I am struggling with right now.<p>I have a CVS repository of PDF and Word docs.<p>The business side uses docx format, so using markdown and generating docx is not really feasible. I have run into issues of people changing the filename and it creating a new entry in the version control. I have a idea I plan to implement to fix this.<p>What I would really like is some linux system that would make it easy to pull the text out of docx and make it searchable. I would want something that could run on the command line that does not have a ton of dependencies.

All of folks at Continuum Analytics use sphinx and readthedocs

We barely have any documentation except some READMEs that are mostly terse and still poorly maintained... If you don&#x27;t understand something, you ask someone.

The most valuable docs for me are rest Api contracts stored in confluence. Easy to collaborate on. Also, getting started guides in confluence for new hires, and architectural diagrams again in confluence for cross team collaboration &#x2F; understanding &#x2F; discussion.<p>As for code, auto generated docs from jsdoc etc. headers are fine but I never use them honestly. I find unit tests to be the ultimate documentation in terms of code level docs.

HN, we are writing our high level overviews as Readme MD files. Any ideas on how we could help condense this info for open source contributors?

We wrote our custom documentation generator for Grape (ruby), something like Swagger, but less rigid.

Adobe FrameMaker and Microsoft Visio, stored in Perforce.<p>Beautiful documents, but it takes a decent chunk of time to create. We do extract some docs via XML to generate code, somewhat backwards from how most engineers merge docs and code.

I work for the government right now.<p>I&#x27;m trying to gather a community of git supporters to push for git.<p>However, after three months I still haven&#x27;t gotten a computer suitable for my job.

My boss decided to use Framemaker with DITA in 2016..

A combination of Github Wikis and a Dozuki site.

swagger.io for the apis + README.md on each service&#x27;s repo

doxygen

Fucking Word docs. Which are checked into source control, except people (who are nominally developers, or project managers who were supposed to have been developers once) insist on versioning in ye olde rename-and-add-a-number style. With PDFs that are manually generated by exporting said Word documents from Word, and then again checked in, and again checked in in multiple renamed versions. Except sometimes only the PDF is checked in, without the source document...<p>So we have a doc folder in the repo that is like staring into the maw of Cthulhu and takes up 90% of our build time on the CI server sucking that down mass of garbage for the checkout.<p>Saner systems have been proposed, but rejected because the powers that be are too averse to change...

We used to use a Mediawiki wiki, which only I would edit. You kind of have to be comfortable with mediawiki syntax (does the job for everything but tables, which suck). So we moved to Confluence, which has a WYSIWYG editor, to encourage more people to document things, upload documents, so on and so forth. Again, I am the only one editing it... so our documentation is &quot;very occasionally write something down, and store it on your laptop or in your private google drive, then spend ages searching for it when someone asks&quot;.<p>So whenever a new staffer comes along, I get asked to give them wiki access... but I&#x27;m the only one here that uses my edits (only ops staffer). Sure, have some wiki access, for all the good it will do you!<p>I really don&#x27;t recommend our model :)<p>Anyway, this is an important point: <i>documentation is not free</i>. It takes time. Even shitty documentation takes time. If you want good documentation, you need to budget time away from other tasks. When I used to work in support, the field repair engineers would budget 30% of their hours for doing paperwork - not <i>documentation</i> specifically, but it clearly shows that &#x27;writing stuff&#x27; is not something that springs as a natural&#x2F;free parallel to other activity.

Related: what&#x27;s the right way to extract inline comments regarding function API stuff from source code?<p>This seems like something that is a really good idea, but is hard to find any projects for it.