How do you document your code?

#discuss #documentation #tools

I am sure this has been discussed before but I am looking for suggestions on how to keep our documentation at work, that is suggestions on tooling. The documentation will be on code, deployment, and how to get started for newcomers. It will also contain mathematical documentation on the business logic.

I have a few requirements for the documentation tool:

It must be private to our company.
Writing must be easy, i.e. available to non-developers.
It is preferrably web-based (either hosted or on-premise).
It must support math notation and code color syntaks.
Single sign-on (Windows domain) is a plus but not a must.

Our code resides on an on-premise classic TFS server but our developers are familiar with Git. The non-developers are not familiar with code repos.

Markdown is a good option but it does have some short-comings. I have used GitBooks myself but I think it is really easy to mess up when linking. At work we have Sharepoint but Sharepoint wikis are just... awful 😒

So, any suggestions are very much appreciated 😊

Top comments (4)

Ryosuke • Apr 7 '18

I've used Slate in the past for API documentation. It works well for generating a slick HTML interface from Markdown files. I'm sure you could just use it for non-API applications.

For other projects I use static site generators. Anything that let's me write in Markdown and translate to HTML, and deploy from a repo so it's readily available to anyone to edit. GatsbyJS is my personal goto, but honestly you can achieve this with other frameworks such as Hugo, Jekyll, or a few React ones.

You can build out a CMS interface for these static repos using Netlify CMS if you have non-developers who feel uncomfortable using git or Markdown.

And you can host everything on a private repo, like a custom GitLab install, and leverage their CI tools to do the build process (so you're not paying monthly fees to cloud-based deployment). And then ideally deploy to a private or local server.