I have been working restlessly these days to migrate our docs to a new system.
Even myself didn’t understand why I was so eager to do this. Isn’t it just yet another place to write docs? As long as you have a place to write docs, why bother so much to setup a new one? Even if the new place is cleaner, nicer, the docs themselves are what really matter, aren’t they?
I manually moved some docs from the old system to the new one. Copy them out, paste to VIM, reformat them as pure text and markup, then paste into the new system. During this process, I suddenly realized why the “place” matters.
Because you simply can’t make a person write decent docs in a lousy system.
The old system is a pain in the ass because its editor is just terrible. And a doc with code snippets appears shitty in this system. And this system has very limited customization options, so that we can’t even remove those stupid twitter/facebook share buttons…
If you ask me to write an article for a newspaper full of nasty ads, will I put all my efforts into it? Probably not. Same thing here.