DEV Community

Jakob Christensen
Jakob Christensen

Posted on

4

How do you document your code?

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 😊

Image of Timescale

🚀 pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applications—without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read more

Top comments (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

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

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

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more