1. 6
    CMS for docs? ask api

I’m searching for a headless CMS for docs. Something that all of our team members can use to improve docs. CMS needs to support tables, code examples, notes etc.

I tried contenful but it’s a PITA with tables. I tried readme but it’s not headless, so pretty difficult to integrate. Gitbook is awesome, but the code examples don’t support tabs for selecting different languages…

It’s weird, there must be something decent out there right?

  1. 2

    I usually just roll my own with GitHub Pages and Jekyll. Find a docs-looking theme and tweak it to your liking.

    1. 2

      Sphinx is quite powerful. The markup language RestructuredText is not as nice as Markdown though.

      1. 1

        I’ve been looking at Antora lately, as I happen to enjoy writing asciidoc much more than reST.

      2. 2

        I’m the initial designer of the Qt documentation, IMO the best-ever developer documentation written by a comparably sized team, and I don’t think even much bigger teams have managed anything much better.

        What I managed was decent, at very low cost, and I didn’t do that by making tables a priority. Tables? What do tables have to do with getting the text right? Or with getting the text written in the first place?

        I suggest that you consider what you really want, and then implement that in top of something like markdown. Make sure the features are ones that matter for your goal and pay close attention to what makes people write and what makes them not write, then iterate. In my case, making people write very-nearly-plain-text in their usual editors, version-controlled, was a key, having someone who showed interest in the result was key, the lack of code examples in the “documentation” part of the documentation mattered, but the style of the output, or tables, did not.

        1. 1

          Ikiwiki is what we use for git based workflows. It supports a blindingly large set of syntax and fits in our normal tmux-git environment but allows people to use whatever editor.

          1. 1

            I’ve started (one of many) side projects called Dumbdown: https://jtree.treenotation.org/designer/#standard%20dumbdown. It compiles to HTML or Markdown. I could add support for tables pretty easily, and whatever else.

            1. 1

              I have been working with Grav for the last few weeks and that could work for you. It has some learning curve, but it is easier once you get the basics down. Essentially, everything is just a markdown file in a particular file system pattern. I don’t think it has tabs for selecting a language though. Just the usual markdown style with three back-ticks and the name of the language.