Ask HN: Which Wiki or internal documentation tools do you use?

We've tried to use MediaWiki and other fancy solutions (inc. O365's SharePoint/online OneNote) and desktop OneNote is the only one that stuck. We have .one files for each major topic with sections and pages within them. It is kind of a "low tech" solution, and maybe that is why it works. It gets out of the way, easy to backup, no downtime, etc.

Although Microsoft keeps threatening to discontinue the desktop version of OneNote.

Its not perfect (Boostnote really only supports local files) but it does mean our shared body of knowledge is versioned to what is in our repos. If someone makes large changes they can work on documentation while they are developing the change knowing that their docs are only released when their change is merged.

If Boostnote was aware of this workflow or allowed editing directly to remote repos it would be pretty much perfect.

Github markdown files for short project specific docs.

And Confluence for everything else including a few technical guidelines.

We're toying with Notion at the moment, but we'll see if we can get critical mass behind it.

We just start to using it for the same use case you mention. And so far the best solution out there.

Generated doc tools like Javadoc/Yard are usually terrible and only good for very specific documentation use cases. If that's all a codebase has, it's a middle finger to developers.

I think another requirement to add is diagramming. I think wiki-style diagramming would be a big help for programmers to better communicate ideas.

I've used external tools like draw.io but the overhead for editing, downloading, and uploading I feel gets in the way. Sadly, we are on confluence but don't use the draw.io plugin [1]. Built-in support for dot, uml, or even ascii diagrams [2] would be big help.

[1] https://about.draw.io/integrations/confluence-integration-2/

[2] e.g. https://github.com/ivanceras/svgbob

We have tickets, git, a wiki, and an agile board there. The integration let us do commits like:

    Added feature X from ticket #33, updated doc at [wikipage]

'Watching' a document is a very important feature which is required in documentation tools. API specs change all the time and developers depending on an evolving API need to check the document on a frequent basis which can be a timesink.

Confluence is also a brilliant tool which supports watching and all the other features listed above, though it can be a bit pricey.

It's not bad. It's not great either. Which is pretty much the best way to describe all Atlassian products. It's unbearable on slow or spotty internet connections. It's riddled with bugs (just the other day my spacebar literally stopped working in their edit view). The formatting gets in your way more than markdown, but at least not as much as something like OneNote.

But, it's powerful. Like any Atlassian product, you can script it to do basically whatever you want. You can organize your company workspaces however you'd like. You can set up tables which can automatically pull summary lines of any other page labeled with a specific label, which is great for automatically building indexes or tables of content.

Overall, I haven't found anything better, and I write a lot of technical documentation for our company.

For comparison's sake:

- Github/Gitlab wikis are pretty bad. There's almost no advantage to using them over just storing markdown in the repository.

- Which, we did for a while, and it works fine, but in its simplicity it misses some of the key features that I do like about Confluence (like those automated index pages and page comments).

- We also used Dropbox Paper for a while; I really like it, but its primarily useful for, let's call them "transactional" documentation (write, get feedback, never look at again); It's not very good at being a Wiki, storing long-term long-form information. And given that Confluence can handle both pretty well, there's not a great argument for adopting a new service from an entirely different company we don't otherwise use.

- We have G-Suite and thus Drive/Docs. The inability to easily write technical documentation with inline/block code makes it a non-starter. No thanks. If Drive added a markdown editor like Dropbox Paper I'd probably push to switch; the search is pretty great, its a platform we already have, and you get a full, amazing document editor for those documents where it makes sense.

- I've never used Quip in a real work setting.

And to make it pretty we use mkdocs material - https://squidfunk.github.io/mkdocs-material/

There's a lot of great extensions that offer more functionality and features too - https://squidfunk.github.io/mkdocs-material/extensions/admon...

There's also extensions not listed in here that you can Google if looking for something specific

You can synchronize with Simplenote — https://simplenote.com/ — which has a mobile version so your notes are viewable on your phone.

You can also use double brackets for wiki functionality to automatically create a link to another page of the same name. For example, [[this]] would create a link to a page called ’this’.

Another option that is good for many people working together is Gollum, a wiki system built on top of Git. It is the basis for GitHub’s wiki pages, if I remember correctly: https://github.com/gollum/gollum

It's a minimalist wiki with markdown support and real-time collaboration features. A lot faster and more lightweight than most of the old school wikis e.g. Confluence, MediaWiki, SharePoint (ugh).

Also has a kanban board view for sprint planning.

The main point that confluence does really poorly (for me) is the lack of an external editor and the absolutely shameful support for Markdown.

If I could edit the page with git like interface and an external editor (like you can do on Github), it would be absolutely amazing and would make it a killer product for us.

Moving to another solution without deep integration to confluence/Jira is not possible since those are being used by product as well.

We are tech company, everyone can learn to use Markdown and Git.