News for hackers. Stuff that matters.

Ask HN: How does your team do internal documentation?

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.

( 18 comments | 14 points | on HN )
Re:Ask HN: How does your team do internal documentation? by aprdm on Friday September 09, 2016 @02:18AM (#12459987)
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.

Re:Ask HN: How does your team do internal documentation? by citruspi on Thursday September 08, 2016 @03:38PM (#12456537)
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.

Re:Ask HN: How does your team do internal documentation? by GFischer on Friday September 09, 2016 @09:46AM (#12462107)
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.

Re:Ask HN: How does your team do internal documentation? by WheelsAtLarge on Friday September 09, 2016 @02:00PM (#12464606)
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.

Re:Ask HN: How does your team do internal documentation? by GFischer on Friday September 09, 2016 @02:47PM (#12465013)
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.

Re:Ask HN: How does your team do internal documentation? by Torgo on Thursday September 08, 2016 @07:57PM (#12458563)
MediaWiki, no registered users. Has worked wonderfully for years.
Re:Ask HN: How does your team do internal documentation? by flukus on Thursday September 08, 2016 @10:26PM (#12459285)
> 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.

Re:Ask HN: How does your team do internal documentation? by stephenr on Saturday September 10, 2016 @09:20AM (#12469048)
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.

Re:Ask HN: How does your team do internal documentation? by spdustin on Thursday September 08, 2016 @07:19PM (#12458332)
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.
Re:Ask HN: How does your team do internal documentation? by jobvandervoort on Friday September 09, 2016 @08:14AM (#12461414)
Cool! Any features that we're lacking? Something we can improve?
Re:Ask HN: How does your team do internal documentation? by stephenr on Saturday September 10, 2016 @09:21AM (#12469054)
Is Gitlab wikis powered by Gollum (or at least feature compatible) ?
Re:Ask HN: How does your team do internal documentation? by orky56 on Thursday September 08, 2016 @05:10PM (#12457369)
Google Docs traditionally but we're slowly transitioning to Confluence. I'm leading by example but it's a work in progress.
Re:Ask HN: How does your team do internal documentation? by jtfairbank on Thursday September 08, 2016 @10:20PM (#12459258)
Tried it, thought it was a pain in the ass. Depends on your team I guess.
Re:Ask HN: How does your team do internal documentation? by bbcbasic on Friday September 09, 2016 @12:22AM (#12459610)
Confluence. Horrific editing experience but good enough for simple docs and understands Jira links.
Re:Ask HN: How does your team do internal documentation? by splitbrain on Saturday September 10, 2016 @03:48AM (#12468181)
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.)-
Re:Ask HN: How does your team do internal documentation? by blabla_blublu on Friday September 09, 2016 @01:11AM (#12459759)
Quip. Love using it - simple and effective!
Re:Ask HN: How does your team do internal documentation? by GFischer on Friday September 09, 2016 @02:47PM (#12465019)
Hadn't heard of it. Looks interesting:

https://quip.com/

Re:Ask HN: How does your team do internal documentation? by jtfairbank on Thursday September 08, 2016 @10:20PM (#12459256)
readme.io - Turns out it works pretty well for non-api documentation too.