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.
19 comments
[ 3.5 ms ] story [ 54.6 ms ] threadFor internal API documentation, some teams use Swagger. There's also some ESDoc usage.
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.
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.
https://quip.com/
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.
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.
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.
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.