1. 26

Hello,

What are you favorite documentation tools for building team knowledge base.

It can be opensource and offer features such as full text search and can be hosted as a static site

  1.  

  2. 10

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

    1. 2

      same here; github wikis are good enough for my use cases. And it’s a normal git repo, so easy to edit/search locally.

    2. 8

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

      1. 7

        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.

        1. 6

          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).

          1. 5

            We’re trying out Notion.

            1. 1

              How do you expect this to play out in the long-term? Tools like these can start out well when you have a set of users that span a whole company. Eventually cost, or just a more trendy tool, cause folks to want to move. This is not a great experience for folks, but it seems to frustrate eng teams more than others. I like Notion’s user experience, so I’m more interested in whether you think they can be sticky, especially for eng teams.

              1. 2

                Disclaimer; I work at Notion.

                I’d like to build a two-way sync tool between Notion and source-controlled documentation so that it’s easier to author in Notion, but pipe that documentation goodness into your IDE, website, public GitHub wiki; have run books cloned locally and greppable in-repo with code, etc. Let the Vim and EMacs fans write content that finds its way into the Notion wiki. That would lessen the lock-in anxiety, too.

                I think the biggest problem with Notion as a documentation tool for code aside from that is search. Search has improved a lot over the last year in general, but Notion’s index is still quite simple. I don’t think we do any specific analysis or indexing for source code snippets or really understanding the semantic layout of your wiki. We have a long way to go there.

                Where Notion is better than other similar tools is that UX, and wrangling projects - especially projects with unusual shape where you might want a more specialized workflow. We get a lot of positive feedback from teams who say “wow we came for the wiki but really like the flexibility to manage this or that process”, as well as teams who say “the editor UX in Notion is so much better than XYZ that we actually write (and organize) our docs”.

                1. 1

                  If that roundtripping was fully supported for third parties I could see how might light up scenarios beyond developers. It seems like the Notion API is fairly fleshed out. Is it complete enough to attempt something like this?

                  1. 1

                    I think you could do a pretty good job with the API. The only limitation is that the API is kinda slow / rate limited.

            2. 4

              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”.

              1. 5

                For markdown based solution, I’d recommend mdBook. Single binary, comes with five themes (one of them can be set as default and user can change it too) and there’s a search option as well.

              2. 3

                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.

                1. 3

                  I would also add that Git forges (GitHub, GitLab) typically render Markdown and a limited subset of Org without even needing some continuous integration. It’s both very convenient and very simple.

                  1. 1

                    We do this, but use a static site generator in a ci pipeline to build and publish the doc site

                  2. 3

                    [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.

                    1. 2

                      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.

                      1. 2

                        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.

                        1. 1

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

                          1. 1

                            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.

                            1. 1

                              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.

                              1. 1

                                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).

                                1. 2

                                  I’ve actually used the Hedgedoc API to extract docs for reuse in a static site generator. It’s not nearly as ergonomic as a native offline mode, but it doesn’t have the benefit of not requiring you to know that you may want a particular doc and preload/save it for use offline later.

                                2. 1

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

                                  1. 1

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