1. 38

Recently, I’ve started to feel the pain of not having a central place to store general documentation where I work. I mean, for individual software projects, a readme in the git repository is usually enough, but there are times when you would like to document something which doesn’t naturally live in a particular repository. Does any of you use any neat software or systems?

  1.  

  2. 51

    We use Confluence, like we did at my last job.

    I fucking hate Confluence.

    1. 7

      Same. It’s awful. Search is a train wreck, and it doesn’t even use wiki-markup.

      We also use something like Doxygen, except it errs out instead of generating the docs.

      1. 6

        I’ll be the counterpoint here… Confluence sucks, but I think it sucks less than the other solutions I’ve seen. At least for certain problems, and especially when you need a resource for non-developers.

        A sibling comment says “Search is a train wreck”. To which I say: try searching google docs. Confluence search will at least show you matches within a doc when you search, so you have a better chance of figuring out which doc is actually the one you want.

        Confluence has the ability to embed various kinds of content in the page, which is quite nice. Google Drawings seems uniquely designed to make ugly drawings. In Confluence, I can use PlantUML or Draw.io.

        Their new editor supports typing markdown keystrokes to do formatting. The rollout has been kind of bad, but I think the direction of the new editor is good.

        “Spaces” can be confusing at first, but I think it will help us scale up to the organization sanely.

        So if the problem you’re solving is “I want to document the API of this project”, Confluence is a terrible choice. If your problem is “I want a place in which all kinds of people in the organization can find docs, discussions, and decisions around various things we’re doing”, Confluence works better than the other choices I’ve seen so far.

        1. 2

          The sad thing with Confluence is they used to (about 5 years ago) have a method of inserting wiki markup so that wiki pages could be generated and pasted in, or if you just didn’t want to use the (frankly awful) WYSIWYG editor you didn’t have to. But they ripped that out.

          Atlassian actually paid us a site visit to gauge opinions from everyone in the company. Pretty much everyone in the company asked for wiki markup to come back, to which they responded “huh”.

          The API for Confluence is also pretty bad. We have some tools for generating document trees, e.g. when creating documentation for a new service we run a script which creates a tree of pages from templates, but little things like not being able to turn off “notify watchers” on an edit via the API means you can hammer people’s inboxes (which in turn makes Gmail mad).

          I agree that it sucks, but sucks less than other solutions. Which in itself is pretty sad.

        2. 5

          We used to use confluence a bit, but we sort of stopped using it because, well, we also don’t love confluence.

          1. 8

            Confluence is awful, but having a constellation of markdown files and Google docs is even worse. One source of truth.

            The value we got from Confluence is that it gave a place where we could keep dev stuff next to business stuff, so it was easy for people to reference things more easily and have less silo-ing.

            My only real complaint is that integrating with Confluence via a bot is a pain in the neck–we did this to have a wiki automatically updated with product information from deploys and builds, and that was Not Fun.

            1. 3

              The value we got from Confluence is that it gave a place where we could keep dev stuff next to business stuff, so it was easy for people to reference things more easily and have less silo-ing.

              Something key here is that business folks generally have little interest in editing Markdown files and using Git. Confluence and other such systems may be monstrously annoying (and they are), but they’re better than alternatives.

              Also, it works in the other direction. Devs want constellations of Markdown, but biz likes constellations of Word documents with comments and tracking. Trust me, Confluence is a better choice.

              1. 1

                We dragged them halfway with Confluence, then? We just need to Zeno them to git and markdown (eventually) ;-).

                1. 1

                  Of course, that goes both ways—I find Con(ef)fluence’s UI so utterly intolerable that I will interact with it the absolute minimum required to not get fired, which in practice means literally never. So now it’s a wiki just for the business side, which is probably better than the “NAS full of outdated Word documents” approach it probably replaced, but it still not very useful.

                  Literally any other wiki software I’ve ever seen would be preferable.

                  But I’m not sure I agree with you that having business and tech share a wiki is a good plan. Business folks love putting paperwork (e.g. “this deployment of this service was signed off on by these people”) into the wiki, which you must never ever ever ever allow, or it will immediately dilute the useful content to homeopathic proportions and make the whole thing useless. So now you either need to be draconian about allowing business folks to put stuff in, in which case they won’t use it, or it turns into a paperwork repository, in which case nobody will use it.

                2. 1

                  Confluence is awful, but having a constellation of markdown files…

                  That’s a bit of a false dichotomy. Most wikis can provide search, history, notifications…

                3. 4

                  We use confluence too. I really wish they never made the change to the “smart” editor that prevents users from editing plain markdown (or similar).

                  Read some of the historical tickets around that change if you’re in the mood to shed a tear.

                  In the end though, the key thing is to have one central jumping off place to get to your documentation and confluence works ok for that.

                  1. 3

                    Hear, hear. It’s a nightmare.

                    1. 1

                      I like Confluence. It has a WYSIWYG editor that actually works. Plenty of plugins for lots of features and integrations. Recently it even gained real time collaboration.

                      1. 1

                        I can’t add anything new here - we too use Confluence and almost everyone hates it, but as I and dangoor have mentioned in other comments, there might not be anything better.

                        One thing we did a while ago was move alert references out of Confluence to a git repo which uses mkdocs. This way if Confluence is down or there’s some network issue meaning we can’t get to it, on-call engineers can still have a local copy of all the alert references.

                      2. 16

                        I’m a big fan of markdown files in a repo. If the repo is git, you can just whack Gollum in front of it, and non-tech users can edit in a browser too.

                        This is essentially what Github wikis are (they use Gollum too) - but they obviously customise to embed the view within the rest of their app.

                        1. 1

                          Nice tip. Can Gollum work with a subdirectory of an existing git repo? ( We store docs alongside code )

                          1. 2

                            Good question, can’t say I’ve tried it, but the docs mention a --page-file-dir option. https://github.com/gollum/gollum#configuration

                            1. 2

                              AFAIK you need to execute gollum from within the root directory of your git repo. But it’ll ignore other files if you want to and displays just markdown files.

                          2. 12

                            I don’t work there, and I’m not sure what system it is, but the Stripe docs are my gold standard.

                            1. 3

                              Those look great, though I haven’t used them in any working capacity. For me the gold standard is Mozilla’s Web Docs. https://developer.mozilla.org/en-US/

                              1. 3

                                as far as I know those are erb templates compiled to static files (sprockets seems to be used for css/js) then served with nginx. so a pretty simple custom solution but written with a lot of care for details (and clearly a lot of time is dedicated to make those great).

                                apparently their internal tools are pretty good too.

                              2. 6

                                We’re currently transitioning to https://notion.so as our single source of truth on these things. It’s not perfect, but it’s discovery and collaboration is must better than Confluence or GDocs, from experience. This is from the perspective of a small engineering team, though.

                                1. 1

                                  That looks somewhat neat, but it looks like it has no Linux support and no web interface?

                                  1. 3

                                    Ah, I can see how you would get that impression from the landing page, but it does in fact have a web interface and I mostly just use it from the browser so that should solve the Linux support issue as well.

                                    1. 2

                                      It’s fully usable through a web browser, but there’s no Linux client, no.

                                      1. 1

                                        The native clients are basically web views. The web interface is what I use most of the time.

                                        1. 1

                                          It’s definitely web based and in browser, the desktop apps are just Electron wrappers. I think there may be an unofficial Linux Electron wrapper too (if you are willing to add to your collection)

                                        2. 1

                                          Thanks for the link. Definitely going to check it out!

                                        3. 5

                                          Sticky notes and water-cooler conversations. Save me.

                                          1. 5

                                            I was talking to a friend today who works in a high-assurance workplace (think defence / safety critical systems / nuclear engineering etc). They have a nifty Docbook based system where /all/ the documentation for their systems is contained within the source code & they can generate PDFs documenting the system (including state chart diagrams and all that kind of thing) from the sources which they can submit to their client / regulator whenever they want. I’ll have to see if they can document how they go about it.

                                            Setting this up was a huge improvement on their previous “do everything by hand in word documents” approach.

                                            1. 1

                                              I assume that the PDFs contain nothing that isn’t just straight from the docbooks, would that be fair?

                                              1. 1

                                                I think they auto-generate statechart diagrams & that kind of thing from text in the source.

                                            2. 5

                                              I’m not happy with it, but we mostly use https://firefox-source-docs.mozilla.org/index.html Older stuff lives on https://developer.mozilla.org/

                                              1. 4

                                                Nothing.

                                                1. 4

                                                  Redmine wiki.

                                                  1. 3

                                                    At work I use a mix of Azure DevOps wikis (markdown in a git repo model) and Confluence. Of the two I think Confluence wins: non-devs have a chance at being able to use it, and it allows for quite sophisticated extensions and embedding (plantuml and ditaa for diagrams for instance, or embedding fragments of docs and avoiding duplication of content).

                                                    Its editor still sucks, mind. If Confluence had any local app option (git+markup, or an old-fashioned app, hell even an offline-capable electron thing) it would be almost incontestable in my opinion.

                                                    1. 3

                                                      It sounds like you want a wiki!

                                                      I use Dokuwiki to organize my own notes (a.k.a. my second brain). It has its own markup syntax. I’m not super thrilled with it anymore but it works fine if you don’t need anything fancy and is very easy to set up.

                                                      At work, our tribal knowledge is in Mediawiki. It’s not trivial to install and get going, but not super difficult either. Lots of extensions, lots of extensibility. Easy to use and has WYSIWYG editing these days, so you don’t normally have to know its markup in order to use it.

                                                      I really want to try BookStack but haven’t gotten around to it yet.

                                                      1. 3

                                                        We use OneNote and Word docs scattered about on SharePoint. There’s nothing good about it.

                                                        Luckily we also have a GitLab instance, so I tend to try and put new technical documentation on a GitLab wiki associated with a repository. Then I can clone the wiki repository and grep it if it ever gets large enough to warrant fast text search.

                                                        1. 3

                                                          Same. We have a big fat OneNote. Hard to update, hard to search, hard to index, hard to link to specific things. I don’t love OneNote.

                                                          1. 2

                                                            We use OneNote and Word docs scattered about on SharePoint. There’s nothing good about it.

                                                            Having a little experience with this, yes, it’s terrible. Search in SharePoint is next to useless and document uploading is baffling (seriously, creating directory hierarchies is an incredible chore). And good luck with history.

                                                            If this is your setup, I pity you, and seriously consider switching to something else. It’s this kind of setup that made me not hate Confluence.

                                                          2. 2

                                                            Sounds like you want a wiki. Originally, we used Docuwiki at work, but we’ve since switched to Phabricator for our ticket tracking and it also offers a wiki.

                                                            So, since the switch, we’ve started documenting stuff in Phriction, its wiki. It’s nice to have everything under one roof: code hosting (though we currently only mirror from elsewhere), code review (which we should use more), ticket tracking with Trello-like card boards and so on.

                                                            At first I didn’t like Phabricator; it had some childish jokes and it’s written in PHP. But over time, I’ve come to like it; it’s quite integrated and seems to do what we need it to without slowing down. We used Jira before, but it became dog slow after a thousand or so tickets in it. Also Phabricator is free software, which Jira most definitely is not.

                                                            1. 2

                                                              Quip, Google Docs, markdown in git repos…

                                                              1. 2

                                                                Confluence I the last two places, before that asciidoc in git. The latter was nice!

                                                                1. 1

                                                                  I’m considering the latter. Do you just use the asciidoctor tool to generate everything, or do you have logic above that?

                                                                  1. 2

                                                                    We used gradle as a build tool and used the plug in for that. Builds would happen on teamcity and we would publish to S3. Note that this was 3 years ago, I don’t know how maintained all that is.

                                                                2. 2

                                                                  A collection of Markdown files in a GitHub/BitBucket/SourceHut repo can work great for developer documentation

                                                                  Wikis also work well, and may be more accessible to non-developers.

                                                                  1. 1

                                                                    We use Confluence on the job which is better than it has been or could be.

                                                                    I personally have been learning roff/troff, and then converting everything into whatever.

                                                                    Confluence likes HTML (sometimes)? roff/troff to HTML

                                                                    Business likes PDF? roff/troff > ps > PDF

                                                                    Confluence sometimes hates HTML? roff/troff > ASCII/any format text > text

                                                                    GitHub likes a smattering of formats? roff/troff > smattering of formats

                                                                    1. 1

                                                                      Are you enjoying learning roff, and would you recommend it to others? Also, what inspired you to learn it?

                                                                      (I have a casual interest in old software.)

                                                                      1. 2

                                                                        I am enjoying learning roff. Yes I would recommend it to others.

                                                                        I was inspired by reading man pages and wondering how the heck something so pervasive, yet so standardized (ish… but I won’t spoil it for you) comes to be.

                                                                    2. 1

                                                                      Go has pretty good built in facilities for documentation, we just point godoc.org at our repos.

                                                                      1. 1

                                                                        In the same repo docs/ directory.

                                                                        If it’s not in a VCS, it doesn’t exist.

                                                                        As to formatting, depends. We tend to use whatever that language/system calls for. Sphinx for Python, etc. If there isn’t a standard for that language/etc, then we do plain text, formatting system(markdown/org-mode/rst) we don’t really care.

                                                                        Like most things, Boring(tm) wins.

                                                                        1. 1

                                                                          Confluence and it’s terrible.

                                                                          Same with my last company and the one before that.

                                                                          1. 1

                                                                            I’m going to evaluate StackOverflow for business (i.e. private SO) to see if it’s a better way of transmitting our institutional knowledge that currently is scattered around Confluence and people’s minds. Does anyone have any experience with SO for teams, the earlier incarceration of it?

                                                                            1. 1

                                                                              Sphinx, with HTML generated output bundled into an image with nginx to serve it. CI/CD is the same as any app.

                                                                              1. 1

                                                                                I used to keep documentation in Markdown files alongside related source and tools - this was an operations type role. It was nice way to keep the docs easily locatable (using foo_tool.py? there’s a foo_too.md right next to it) as well as the obvious benefits that git’s history provides.

                                                                                I’ve since moved to a different company that doesn’t have a standardized practice, and as a result docs have ended up in various wiki tools and microsites. It’s really awful.

                                                                                1. 1

                                                                                  Markdown in a git repository mostly. Sometimes we use YAML for metadata.

                                                                                  1. 1

                                                                                    Google drive and Google docs and slides. Seemless sharing and real-time co-editing is quite valuable, and the comment system is mostly adequate.

                                                                                    1. 1

                                                                                      We have an internal wiki. The code is usually documented minimally, it kinda sucks, so the wiki is incredibly helpful.

                                                                                      1. 2

                                                                                        At my last job, we had a self-hosted MediaWiki instance. It worked great because the friction is very low. We could just throw raw thoughts and refine it later thanks to the “piranha effect”.

                                                                                        However, things can get messy pretty fast without some discipline. That is the drawback, I suppose.

                                                                                      2. 1

                                                                                        For internal docs we have a Sharepoint wiki for company-meta related stuff, and Gitlab project wikis for project-specific docs, and a Gitlab project itself to use its issues as a knowledge repo.

                                                                                        Sad thing is that everyone is too busy to contribute anything to the documentation. RIP future us.

                                                                                        1. 1

                                                                                          Our infra team put together some Markdown to Confluence ETL scripts so we put our stuff in GitHub markdown and deploy that to a team namespace in Confluence. I can’t stand confluence but since we need non-engineers to view the docs without having to pay for a GitHub account and since we use GitHub.com this is easy enough.

                                                                                          1. 0

                                                                                            Nuclino. It’s okey.