Ask HN: What do you use for company-wide documentation | Hacker News Reader

Ask HN: What do you use for company-wide documentation

20 pointsgtf2120 comments

I've tried using Github Wikis, which is fine for developers, but not ideal as I have to grant everyone access in the company access to GH. I have hosted API documentation, but that's not suitable for everyone in the company.

I'd like to host documentation on everything from how are products work, how our internal systems work, what certain procedures are &c. somewhere that everyone in the company (and only in the company) can access them.

I considered Google Sites (as I assume I can use our Google Apps logins for authentication) but was wondering if anyone here had done this before, and what they would suggest.

Something like a Wiki would be great as it should be updatable by everyone on the team, but I've always found MediaWiki a bit of a mess.

View on HN

GitHub repos full of markdown. A Jenkins job rebuilds using a static site generator (mostly Jekyll, a couple use Pelican). Each team has a subdomain on our internal network, so like accounting.company.internal type thing. Most have a TOC type landing page with popular links. Commit markdown -> site rebuilds itself.

GitHub desktop is easy to use and we're generally staffing under 35's, who are pretty computer savvy. They may not get the in's and out's of Git, but Customer Service people are rebasing (their internal knowledge base is built the same way).

Upsides for users: Using whatever editor you favor. Anyone can help support your teams efforts (copywriters are committing tweaks all the time to every teams repo, use dem writing skills). We avoid fragmenting and putting multiple UX's in people's faces.

Design folks even made some CSS that's easily injected to match company branding. Optional to use of course.

This is for the things teams can/want to share. HR obviously doesn't people's salary info in there.

We needed GitHub anyway. So we found a way to avoid spinning up some kludgy wiki framework with a shitty WYSIWYG editor no one wants to maintain or paying money for some janky thing like Jive or Yammer.

Quick question: static site generated is launched into some server accessible via a private network? or exposed publicly (S3/Github pages)?

I was also wondering how you were handling authentication.

Thanks, that's really useful. I think this gives me the greatest portability.

Confluence

My company uses Confluence as well. It's been really useful - we use the Q&A and also document features a LOT. It makes sense since we are mostly on the Atlassian stack (JIRA, & Confluence)

Previously we used Google Docs. However, in every company I've worked at I've seen this tool fail. People start of using it but after a while people forget. The main issue I think is that docs lacks key capabilities in discoverability, search, and engagement; essentially confluence does a way better job of pulling our team back in so we "remember" to use it again. We have a senior manager who is addicted to the Q&A feature and looks at it daily to help answer questions from our team.

The main tools I've seen consistently fail in large orgs for documentation has been Google Docs, Google Sites, and Wikis. All of these fail in the "living" component of "living documentation". They tend to be places where you write and things die / don't get updated / are never seen.

Why do you think Google Sites or Wikis fail where Confluence succeeds? I've never used Confluence (and don't really like Atlassian products in general), but am willing to try it.

Have been playing with Google Sites and the main thing I'm worried about is portability if I should choose to go with something else. It seems hard to export.

Comparing Confluence to MediaWiki...

Confluence lacks categories. You are stuck with hierarchy. It's more like filesystem directory structure than tags. This gets awful once you have a lot of stuff.

Confluence does not provide direct wikitext access. You might not think you need direct access, but then one day you want to turn a bunch of data into a big table.

Confluence, obviously, doesn't scale as well as MediaWiki. Nothing does. You'd hate to find yourself needing to migrate from Confluence's closed ecosystem over to MediaWiki once you hit the limits.

Confluence lacks the familiarity of MediaWiki. Pretty much everybody has seen MediaWiki in action on Wikipedia. This is comforting. People know what to expect from MediaWiki.

I assume you would say the same with Google Sites then? I've always found MediaWiki a bit of a pain to work with, but would definitely prefer more of an open ecosystem to a closed one.

Is there good hosted MediaWiki? I have too much other infrastructure to run and would rather not have to run more myself.

Can MediaWiki create a layer of separation between users? IE only users in group "Engineering" can see that groups documents while all users can see group "AllCompany" documents?

The main issue with Google Sites is there's a much higher level of friction for creating documents and then more importantly it's much more difficult to find things (search is way better on Confluence).

I can't speak as much on Wikis as a category but the ones I've seen at orgs are difficult to set up and manage. I have also found that non-technical people have more trouble using Wikis that Confluence.

Some legacy projects are using Microsoft Word (never use it for documentation!) hosted on a Sharepoint server and XWiki (http://www.xwiki.org).

For new projects we use markdown hosted on our Gitlab or use MkDocs (http://www.mkdocs.org/).

I recommend you to have a consistent documentation support to avoid having documentation in multiple places.

Another vote for Confluence.

Google Docs (for collaboration), http://phabricator.org/ (wiki), Looking into a new product called Notion.

I have tried Notion and it has a lot of features and stuff. But I prefer plain markdown that I can edit from my editor and push to the server.

SharePoint, It's awful.

At previous places we used various wikis which were much better. Confluence is the easiest for non-technical people.

My last company used a self-hosted http://twiki.org/ as intranet.

readme.io - works well for non-api documentation too

Self-documenting code... really

Clearly you didn't read the original question:

> I'd like to host documentation on everything from how our products work, how our internal systems work, what certain procedures are &c.

Reply on news.ycombinator.com