
Ask HN: How does your team do internal documentation? - TheGRS
I&#x27;d like to know how others are doing internal docs with their teams. Just curious. There are a lot of options out there, many of which solve different problems. You can collaborate on Google Docs, generate docs straight from your code, use Confluence or any number of other wiki tools out there.<p>Our team currently uses Jive, which has no support for markdown or rst. It&#x27;s also notoriously hard to search for things if you don&#x27;t know what they are already. It does have the advantage of being used across our company, but for engineering-specific docs it tends to not be optimal.<p>So I&#x27;m just curious what others on HN might be using.
======
aprdm
Confluence. Good integration with Jira but it's a NIGHTMARE once you have too
many people in a team / too many teams.

It's really REALLY hard to find content. The search is useless. (I am talking
about >2k people, all trying to use confluence to document several things)

I guess it depends on the organization and how they structure things but I
don't like it.

Previous company:

github. Very dev focused but it simply works. Markdown does wonders.

------
citruspi
We previously used GitHub and put some stuff in Basecamp. Over the last year
we've moved from Basecamp to Confluence and have slowly migrated documentation
from GitHub to Confluence.

For internal API documentation, some teams use Swagger. There's also some
ESDoc usage.

------
GFischer
Current company: SharePoint. I think it's no good for that use case (TBH, I
don't like SharePoint for anything).

Last company: Confluence. Worked pretty well, although we did need to
customize it to fit our needs (same with Jira).

I still haven't found a "holy grail" (Confluence was decent enough, but I
still wouldn't recommend it unreservedly).

Search is a key feature which most do badly.

~~~
WheelsAtLarge
Last company I worked for we used Sharepoint. Ultimately it was a waste of
energy. The information was hard to get to (the irony, given Sharepoint's
selling point of easy access to data) and there was no easy way to update it.

Before that we used Word files and the network's file system, which worked
better than Sharepoint.

I don't think the technology is the key to keeping documentation relevant.

Ultimately there needs to be a policy of how to keep documentation up to date
and in order AND someone needs to make sure the policy is followed.

Documentation is a balance between keeping it useful and not being so detailed
that it's hard to maintain.

~~~
GFischer
I agree with your points. Tech isn't the key, but it's definitely an enabler.

Some key features for a good documentation system IMO are :

\- that it has to be frictionless both to add information and to use it (and
Sharepoint isn't), \- someone has to stay on top of it (that's the most
important thing IMO), \- and information has to be easy to look up (another
Sharepoint failing).

Word files on a file system, with something to make it searchable, would be
pretty decent for a few users (too bad Google Desktop Search has been
discontinued). For multiple users or sites, concurrency and versioning will
probably be a problem.

Sadly, many companies get carried away with security concerns and end up with
less than optimal solutions.

I guess that's why people like Git whatever for it.

------
Torgo
MediaWiki, no registered users. Has worked wonderfully for years.

~~~
flukus
> no registered users

This is key, many companies gimp there documentation process with too much
access control. Recently for instance, I wanted to update the company leave
policy page with a link to the application form but couldn't because it was
locked to HR.

~~~
stephenr
I'm not that familiar with the auth situation for your wiki of choice, but "no
registered users" isnt the only solution to "too much access control".

Having people authenticate as themselves, but still allowing global write to
the wiki for all users gives you an electronic paper trail of who modified
what.

Another solution might also just be "the right amount of access control".
Maybe there's a good reason only your HR department can edit the leave policy
page, and you could/should have asked HR to update the page, or asked for
access to edit it yourself.

------
spdustin
We use GitLab wikis and the "gollum" gem locally if we're in the mood to have
a UI locally without having to go to GitLab's site.

~~~
jobvandervoort
Cool! Any features that we're lacking? Something we can improve?

------
orky56
Google Docs traditionally but we're slowly transitioning to Confluence. I'm
leading by example but it's a work in progress.

~~~
jtfairbank
Tried it, thought it was a pain in the ass. Depends on your team I guess.

------
bbcbasic
Confluence. Horrific editing experience but good enough for simple docs and
understands Jira links.

------
splitbrain
DokuWiki. We have an internal wiki and we have a wiki farm to easily set up
project wikis (great for collaboration with the customer on specifications
etc.)-

------
blabla_blublu
Quip. Love using it - simple and effective!

~~~
GFischer
Hadn't heard of it. Looks interesting:

[https://quip.com/](https://quip.com/)

------
jtfairbank
readme.io - Turns out it works pretty well for non-api documentation too.

