Ask HN: How does your team do internal documentation? | Hacker News Reader

Ask HN: How does your team do internal documentation?

14 pointsTheGRS18 comments

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

Our team currently uses Jive, which has no support for markdown or rst. It's also notoriously hard to search for things if you don'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.

So I'm just curious what others on HN might be using.

View on HN

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.

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.

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.

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.

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.

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

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

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.

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.

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

Is Gitlab wikis powered by Gollum (or at least feature compatible) ?

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

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

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

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

Quip. Love using it - simple and effective!

Hadn't heard of it. Looks interesting:

https://quip.com/

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

Reply on news.ycombinator.com