DEV Community

loading...

How do you document your code?

Jakob Christensen
Actuary with love for programming. Besides coding, I love Icelandic horses, math, and photography. All featured photos are my own.
・1 min read

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 😊

Discussion (4)

Collapse
whoisryosuke profile image
Ryosuke

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.

Collapse
t4rzsan profile image
Jakob Christensen Author

Thank you for your answer.

I seems like good advide to use static site generators and I will dig into that.

BTW, I enjoyed your blog entry "New blog, new brand, new stack" which I bookmarked.

Collapse
ben profile image
Ben Halpern

I too would love to see answers. This is a topic of evergreen uncertainty for me.

Collapse
t4rzsan profile image
Jakob Christensen Author

Well, the response has not exactly been overwhelming :-)

Forem Open with the Forem app