
Ask HN: Which Wiki or internal documentation tools do you use? - sdedovic
I am curious what internal documentation tools people are using. My current use case is an engineering handbook and internal documentation that isn&#x27;t related to any specific codebase.<p>Some basic requirements are:
- searchable
- code snippets
- hyperlinking<p>I know of a few tools and I&#x27;ve even worked at companies that use git repos with markdown. I&#x27;d love to hear everyone&#x27;s thoughts.
======
013a
Confluence.

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.

~~~
kiejo
If you want something similar to Dropbox Paper, but better optimized towards
long-term documentation, you should give Nuclino
([https://www.nuclino.com](https://www.nuclino.com)) a try. In terms of
organization capabilities it is similar to Confluence. But I'm the CTO so I'm
obviously biased.

~~~
cclements
Beautiful looking product. Any plans for a self-hosted version? Cloud based
storage of a lot of information I deal with is a no go.

~~~
kiejo
Thanks for the kind words. Unfortunately we have no plans for a self-hosted
version. We understand that this is a no go for certain companies and types of
information.

~~~
Aeolun
Basically all enterprises. We really need a viable alternative to Atlassian :/

------
juvoni
Notion ([https://notion.so](https://notion.so)) All in one workspace,
combines, trello, airtable, evernote, and docs. Great embed support and
awesome for small teams and personal use. It's a modern day commonplace book.

~~~
anant90
The only reason I gave up on Notion sometime last year was that it was mind-
numbingly slow. Great product otherwise.

~~~
L_Rahman
It's gotten faster and is getting faster over time. It was much, much worse a
year ago which makes me believe that the team is paying attention to speed.

Compared to the main competitor mentioned here - Confluence - it is blazing
fast.

------
nikivi
My entire wiki lives on GitHub
([https://github.com/nikitavoloboev/knowledge](https://github.com/nikitavoloboev/knowledge)).

I then use GitBook to publish it on the web and have fancy features like
search and contents table on the side.

[https://wiki.nikitavoloboev.xyz](https://wiki.nikitavoloboev.xyz)

Been using this approach for over a year now and I love how seamless the
workflow of updating files in Sublime Text, pushing it to GitHub and seeing it
live is. At this point my entire knowledge base lives online and is
referencible and I love it.

The way I approach updating the wiki is in the wiki too:

[https://wiki.nikitavoloboev.xyz/other/wiki-
workflow](https://wiki.nikitavoloboev.xyz/other/wiki-workflow)

~~~
unixhero
It's a pretty good wiki! I'm reading some of your material now :)

------
Ninjaneered
MediaWiki.

The downside is that to get it running with a good set of extensions that
optimizes it for enterprise use takes a bit of an effort.

The upside is that once you do, it becomes an incredibly powerful tool that
most users adopt without complaint. It hits all the OPs requests for
searchable, code snippets (with syntax highlighting), and hyperlinking. When
you add the ability to store and reuse structured data (Cargo or Semantic
MediaWiki) it really becomes powerful.

Others I've tried:

\- SharePoint (this is so bad it pains me to mention it)

\- Confluence (not bad, but lacks structured data and seems to be focused on
serving smaller teams vs. an entire company)

\- OneNote (great for personal use, not as great for teams, especially not
great at tracking multi-user changes)

\- EverNote (great for personal use, not as great for teams, especially not
great at tracking multi-user changes)

\- Salesforce Knowledge (Didn't get too deep, but seemed better for help desk
answer queue than internal documentation)

------
chrisanthropic
I'll mention clubhouse.io every chance I get.

It's billed as a Project Management software (and it's great at that) but it
can be great for documentation because it:

\- provides hierarchical nesting (Milestones / Epics / Stories)

\- each object can have a relationship to another (related, blocks,
duplicates)

\- each object offers a markdown text area, lists, github PR
links/integration, comments, and can be moved between various stages (standard
scrum stages or your own custom ones)

\- each object can be assigned multiple owners, requesters, and followers

\- each object can be tagged

\- search by title, tag, owner, state, etc.

\- each object can have files uploaded and attached

This allows me to track why the work was done, how the work was done, and what
work was done, while providing a nice README as a comment.

Everything can be edited, or others in the team can leave their own comments.

It's odd for sure, but I love it.

------
epage
> Some basic requirements are: - searchable - code snippets - hyperlinking

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/](https://about.draw.io/integrations/confluence-integration-2/)

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

~~~
aasasd
Mermaid is a “Markdown for diagrams” that seems to use a more semantic markup
instead of ASCII art:
[https://github.com/knsv/mermaid](https://github.com/knsv/mermaid)

Would probably work nice as a plugin for a wiki.

~~~
Ninjaneered
I've been using Mermaid with MediaWiki and it has a lot of promise. Since
Mermaid lets me generate diagrams from text and MediaWiki lets me store and
modify structured data, I can have MediaWiki pass Mermaid data to generate
graphs/diagrams that stay up-to-date as the wiki changes.

I would like to see Mermaid be able to group sibling nodes[0] though, once I
can do that, I can autocreate really nice organizational charts :)

[0]
[https://github.com/knsv/mermaid/issues/637](https://github.com/knsv/mermaid/issues/637)

------
stevebmark
Confluence has nailed this product for engineering companies. So far I haven't
seen anything that beats it.

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.

------
zzaner
Nuclino ([https://www.nuclino.com/](https://www.nuclino.com/))

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.

~~~
kiejo
Thanks for mentioning us (I'm the CTO)! Let me know if you have more feedback
or questions.

~~~
pouta
How can I contact you?

------
avitzurel
We use confluence. It integrates with Jira and SAML so we have all of our
users in there and it's really convenient to mention a ticket number or a team
member and have it automatically import the details.

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.

------
me551ah
Phriction which is a part of phabricator is an excellent tool, it supports all
of that and the ability to 'watch'.

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

------
DanielBMarkham
I installed MediaWiki for a personal project, and I love it. I've used a lot
of other tools. Somehow the fact that the Wiki folks have heavily used the
tool brings out all of the features you'd ever want, even if the
implementation might be a bit clunky at times.

------
qerim
[BookStack]([https://www.bookstackapp.com](https://www.bookstackapp.com)) -
Opensource, built with Laravel. Been using it for a few months and it’s been
fantastic so far. Supports LDAP integration, markdown and a lot more!

------
ArmandGrillet
Stack Overflow for Teams works great from my experience. Having a wiki using
Confluence is good for questions related to travel and processes but SO is the
best for engineers due to its integration with Slack and ease of use (fast
search, good formatting, tags).

------
hanniabu
Mkdocs - [https://www.mkdocs.org](https://www.mkdocs.org)

And to make it pretty we use mkdocs material -
[https://squidfunk.github.io/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...](https://squidfunk.github.io/mkdocs-
material/extensions/admonition/)

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

------
BenoitP
Redmine

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]
    

The ticket and wikipage reference will be clickable in the interface.

------
ewood
Boostnote ([https://boostnote.io](https://boostnote.io)) with notes stored in
the relevant repos.

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.

------
drugme
I'd be curious if anyone can summarize the tradeoffs between Confluence +
MediaWiki at some point. From what I've seen it seems to come down to:

(1) MediaWiki is definitely more responsive (Confluence can be quite slow)
and, importantly, considerably more expressive -- provide you can learn
Markdown, which basically anyone can.

(2) But you're essentially stuck with email-based logins which can be a
dealbreaker to some organizations (MW does support OAuth in theory, but only
in theory it seems -- the setup seems to be basically not supported).

~~~
Karunamon
I find that the admin side of Mediawiki is downright painful. Installing
plugins requires mucking around in a config file on the server (it’s just
another PHP app), and any errors in that file lead to a blank white page,
rather than a useful error message.

I also found scaling MW harder than Confluence, as unintuitive as that sounds.
Same goes for troubleshooting speed problems.

~~~
drugme
Good to know - thanks

------
luistrevino
Nuclino ([https://nuclino.com](https://nuclino.com)).

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

~~~
zzaner
Agreed, we started using it too.

------
devinjflick
I'm a fan of WikiJS. Though I havent personally gone through setting it up,
the last two web projects I worked on used it. I found the UI intuitive and
easy to use. I loved being able to updates either in a code editor or in the
browser UI.

[https://wiki.js.org/](https://wiki.js.org/)
[https://github.com/Requarks/wiki](https://github.com/Requarks/wiki)

~~~
Grimm665
We also use WikiJS, it is great. The fact that all the articles are stored and
checked into Git in the background is great for keeping track of who edits
what, undoing accidental changes, and keeping the wiki content agnostic to the
platform.

That being said, there is room for improvement. Image handling is not great,
and a lot of the components feel simplistic and could be fleshed out
(permissions, indexing/search). Dead simple to set up though, especially with
Docker-compose.

------
Someone1234
The desktop version of OneNote.

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.

~~~
amf12
We use OneNote at work. I don't really like it as a Wiki tool. Its a superfast
solution to get the work done, but the search sucks. Its difficult to get it
organized if there is a lot of documentation. Its amazing to use as a personal
notebook but not wiki.

------
MrCheese
I noticed here that noone seems to have mentioned using a static site
generator for this.

We are currently evaluating tools for this with much of the same requirements.

My current idea for this is to use Hugo with [https://themes.gohugo.io/hugo-
theme-learn/](https://themes.gohugo.io/hugo-theme-learn/) as the theme. It has
search, code snippets and such. Does anyone have experience with doing it this
way?

------
fran7118
I've used [Wyam]([https://wyam.io/](https://wyam.io/)) for some dotnet stuff
and it works pretty well. Docs are written in markdown and it generates a
static site with them. It can also generate api docs pages (with a search
interface) from C# source files or compiled libs which was pretty cool IMHO.

------
hypertexthero
nvAlt 2, a fork of the original Notational Velocity, is a good option for
personal use that supports MultiMarkdown:
[http://brettterpstra.com/projects/nvalt/](http://brettterpstra.com/projects/nvalt/)

You can synchronize with Simplenote —
[https://simplenote.com/](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](https://github.com/gollum/gollum)

------
thangalin
[https://www.xwiki.org/](https://www.xwiki.org/)

Using XWiki the following documentation architecture is attainable:

[https://i.stack.imgur.com/nEIXG.png](https://i.stack.imgur.com/nEIXG.png)

------
matt_the_bass
We needed something simple and easy for non-dev/engineers to use. We’ve been
using new google sites for about 6 months and have been pretty happy with it.
We’re already gsuite users so it works nicely with that.

------
kull
For non-technical team it is self hosted WordPress, goggle docs and google
websites. For dev team google docs for project specs and documentations
written as .md files on a separate doc repo.

------
unixhero
For my own projects, I use this wiki; it's amazing:

BOOKSTACK - [https://www.bookstackapp.com/](https://www.bookstackapp.com/)

At work:

Confluence

Preferred tool for work:

Google Drive / Text Writer and Spreadsheets

------
gnulinux
For personal stuff I use org-mode of emacs. At the work, we use Quip.

------
vkaku
I love TikiWiki for very elaborate setups.

These days, I use a Git<->Markdown based hosting. I also wrote a small Flask
script to serve contents from the repo. This makes it Heroku-able.

------
stunt
We have a few docs generated by Docsify for technical guidelines and
handbooks.

Github markdown files for short project specific docs.

And Confluence for everything else including a few technical guidelines.

------
Joe8Bit
Quip. It's okay. Not blown away with it.

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

------
wim
We built Papyrs ([https://papyrs.com](https://papyrs.com)) for this!
(disclosure: co-founder)

------
hidden_sheepman
Dokuwiki, easy to setup and works great.

------
jdlyga
Confluence works really well. It's easy to search through, edit, and create
diagrams.

------
hiroshi3110
[https://scrapbox.io](https://scrapbox.io)

------
h0p3
Tiddlywiki!

------
juandazapata
Google Docs

------
jaxn
Vuepress.

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

------
thetest3r
Had base-tier Confluence at one company. Super nice.

------
wozmirek
Confluence.

------
tempotemporary
Sphinx doc

------
oneplane
Confluence

------
bberenberg
Confluence

