
Ask HN: What do you use for company-wide documentation - gtf21
I&#x27;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&#x27;s not suitable for everyone in the company.<p>I&#x27;d like to host documentation on everything from how are products work, how our internal systems work, what certain procedures are &amp;c. somewhere that everyone in the company (and only in the company) can access them.<p>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.<p>Something like a Wiki would be great as it should be updatable by everyone on the team, but I&#x27;ve always found MediaWiki a bit of a mess.
======
WallowingB_36
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.

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

~~~
gtf21
I was also wondering how you were handling authentication.

------
emilburzo
Confluence

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

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

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

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

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

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

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

------
akulbe
Another vote for Confluence.

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

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

------
flukus
SharePoint, It's awful.

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

------
mtmail
My last company used a self-hosted [http://twiki.org/](http://twiki.org/) as
intranet.

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

------
probinso
Self-documenting code... really

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

