Github wiki/readmes are ok. IMO it’s harder to build and establish the discipline to document stuff than to actually write it down.

Text files checked into the source repository. Unix is my IDE.

Everywhere I have worked I have been forced to use Atlassian Confluence, but if I had to choose and I could choose anything I want at any cost, I would use https://www.craft.do/ .

If you are looking for an open source option guess look at some of the self hosted wiki options such as:

https://js.wiki/

https://www.dokuwiki.org/dokuwiki

https://www.mediawiki.org/wiki/MediaWiki

https://www.bookstackapp.com/

I haven’t used any of them myself to give a recommendation.

I just built a knowledge site with docusaurus.

I’m not a web programmer, but it was ridiculously easy to set up, and super easy to deploy to GitHub pages. Looks great and you can write content in plain Markdown (.md) or in Markdown + JSX (.mdx).

We’re trying out Notion.

Any old school wiki based on a simple enough plain text format to be written by hand. MediaWiki and similar. Or even markdown based solutions such as Jekyl. Or a git repo with markdown files, or Restructured text, or org files. GitHub and other fit hosting solutions offer formated display of these files in their web repo browsers.

WYSIWYG sounds like an usability obvious choice but that is an illusion. After less than a day of usage you’ll run into absurd sufferable pains because of it.

Documentation is by definition technical. To negate all the advantages of robust, versatile and durable format for the sake of perceived user friendliness is a huge mistake.

I am forced to use confluence because of professional reasons. Literally every day I see some display failure making ng the content scrambled or unreadable, or notes saying “ replace x by y in the text, confluece won’t let me paste the word x”.

I recommend a VCS(like git) with a bunch of files in it, in some format that makes sense to you(typically Markdown, but whatever). You can spruce it up with one of those wiki products that take files on disk as their storage. There are lots of those, but again, whatever.

The format is basically permanent, it’s in a VCS so history is kept, and everyone can keep their own copies and send updates as they choose.

[At work] I use plain old Markdown documents in a on-prem instance of GitLab but, if I was to set up something from scratch, I’d start with ikiwiki.

Having seen various teams try various things, I suggest that documentation of the code itself needs to live in the same repository as the code itself. When the code and documentation exist in different places, they always drift apart over time. When code and documentation live together, it’s easier for developers and automated tools to check for discrepancies, and to spot divergence during code review.

Design documents can live outside the repository as they describe ideas at a certain point in time. Documents aimed at non-developers who won’t check out the source code don’t belong in the repository. High level overviews of the system might live outside the repository, but the risk of divergence still exists, as does the need to publish them for non-developers to view.

I think it’s extremely hard to beat markdown or text in a vcs repo. You can use a static site generator to build it and publish as a website if you want that functionality. Lots of git hosting solutions offer in browser viewing and editing as well. For those of us who prefer our own editors we can easily use that. It has the lowest overhead to keep up to date and easiest discoverability I think. You can even have most of the development documentation co-hosted with the application itself which makes it even easier to ensure the documentation is kept up to date via code review checks. Some of them can even be automated.

Wiki’s require extraordinary gardening effort to keep up to date so long term discoverability becomes a nightmare. Wiki platforms all seem to have the worst editing experience as well.

Discourse! Collaborative markdown with access control, and you can /pub/ publish some pages.

We use markdown files checked into the relevant repository and use mermaid to add diagrams.

The main reason for keeping docs in the repo is that it is easier for so many reasons:

• searchable; search for an environment variable, find docs and code
• accessible; no need to fight with other tools and permissions
• permanent; no need to worry about tool migrations, losing doc history etc.
• low friction; if docs are in place next to the code, it’s more likely to be updated
• offline; I can use the docs while on a plane/ship etc.

Higher-level concepts which cover multiple repositories go into another repo called “engineering-docs” but use basically the same format. We usually render the markdown into static websites using Hugo.

I was very impressed with Material for MkDocs: https://squidfunk.github.io/mkdocs-material/. It is very easy to get started with and you get a decent-looking site. It’s very configurable, for example it’s just 1 setting to change and you get a top navigation instead of a sidebar. Most Python project use it.

I like hedgedoc but I wish it could be used offline for emergencies.

I wish there was something like logseq with crdt (free and open source).

As of now, Google docs for flowing things and the ease of external sharing, and a version controlled docusaurus site for relatively stable things.

Markdown in a repository, maybe some graphs, etc if necessary.