Dropbocumentation
Every time a programmer goes away for a few days, a piece of infrastructure they know best breaks. That's just Murphy's Algorithm.
If they they had only written a 100-word overview with some examples, that would have saved someone else a painstaking day figuring out how things should work, why they suddenly don't, and righting the world once more.
How do you make it likely that everyone writes down what they know while it's still fresh? Think of edits as conversions (in the analytics sense) - our funnel stretches from signup to viewing to editing, and we want to maximize the number of edits.
How do we optimize the 'edit' conversion rate for a wiki?
-
Editing should happen in the same mode as viewing. If you have to click 'edit', then wait for a page refresh, then scroll down inside a teeny textbox in a browser, then hit save to see your changes ... those steps create a barrier to entry. The conversion rate of views to edits will drop dramatically. Typos, inaccuracies, inscrutabilities and out-of-datenesses will accumulate.
-
It needs to be as available as possible. All and only your team can access and contribute to it, even if they're on a different computer or offline.
-
Consolidate everything in one or two searchable places. When it's hard to find something, you won't want to start looking. If you have to search one by one through a wiki, your email, a bug tracker, the version control commit log and comments in the codebase, you'll end up just tapping someone on the shoulder - the knowledge will never get planted in a way that it can grow.
-
No special knowledge. Wiki markups are confusing and confusable. WYSYWYG editors are a good start - but editing text in most browser textboxes feels like typing with chopsticks. And proprietary document formats are opaque and constricting.
-
No barrier to exit. I want to be able to easily (and ideally automatically) grab a dump of all our documentation, both as a backup and as an export.
After reviewing these possibilities over and over, these are the best solutions I've come up with for Memrise:
-
A few monolithic Google Docs. This has worked reasonably well, except that Google Docs still falters in an unwieldy and buggy way when dealing with even medium-sized documents. Boooo!
-
Etherpad clone. They seem pretty expensive for multi-user monthly subscriptions, and seem weak at linking and searching. Plus, they don't work offline, and I don't trust the companies behind them to be around in 5 years' time.
-
Text files in Dropbox. The main downside to this is that you can't easily inter-link text files, and they lack formatting which makes them ugly to read. But they have no barriers to entry whatsoever.
In an ideal world, someone would build a nice (optionally hosted?) wiki solution pulling and formatting Dropbox text files as webpages to give you the best of both worlds, perhaps combined with a few desktop apps and extensions to make offline viewing editing more pleasant.