In our organization we have been dealing with the lack of documentation (or chaos on it, what it essentially the same) for long time already.
At the beginning I was the first one in opposing in making too much investment in documentation, mostly because the amount of resources needed to keep documentation updated was overpassing our capabilities. And I consider that an out-of-date documentation is worst that not having documentation at all.
But we are growing, new people is joining us every month (week) and they feel completely lost, and the same questions are arriving again and again, and there is not any central person to ask all of them.
We decided we have to invest in documentation.
And, I, as the technical responsible, started taking this very seriously. I staid full days creating pages and pages of documentation about our systems and how to operate with them. I was using Google Docs just because it was easy to use at least to create the first version of it, then, when the structure of the documentation was emerged, I would think what would be the most appropriate system to allocate it for the long term.
Working on this was not very rewarding. I found my self writing detailed information about things that maybe none was gonna read ever. It was a very solitary work because even if any one could contribute to it it is difficult to distribute the work, specially at the beginning when the structure was still not defined. The velocity that our system was changing and growing was faster than my velocity in writing documentation, making it impossible to feel that I was doing any progress.
And above all, for me (and most of my colleges), writing documentation was a very boring task.
Then we changed completely.
How can we make the documentation generation an engaging activity?. How can be sure that we are writing the documentation that is needed and no more?. How can we involve everybody in the creation of our knowledge database?. How can we make sure the information is accessible?
Then we think in the Question/Answer systems.
Where do I go to find solutions to my problems when I am stuck in a programming issue? In what place I have collaborated the most in sharing knowledge with others? What place makes me feel good spending time sharing knowledge?
I am talking about StackOverflow.
We thought we need something like this to our documentation problem.
There are many things that makes this an obvious decision:
- Documentation is created "on demand": some has a question and someone else answer it. So the documenter knows that she is helping someone, a concrete person. Making it feel helpful with the immediate reward of the recognition.
- Everybody can create documentation: These systems doesn't require any technical skill, they have nice interfaces, they are build to remove any friction in the generation of content: styling, uploading images.
- Not structure: You don't need to think where to put this piece of information. You don't need to follow an index. Maybe a bit doubts with the category or the tags, but it is minimum
- Information is accessible: these systems have a very nice search engine that allow us to not only show you results of your search but also pointing you when you are asking something that has been already answered.
- Information is sharp and to the point: I have a question I want a concrete answer, I don't want to read a full theory article about generic information.
- It is funny: some inner gammification mechanisms make us feel good when we interact with the systems.
We were looking for different systems and even I love [StackExchange](https://meta.stackexchange.com/questions/16054/is-stack-exch...) we decided finally for its younger brother [Discourse](https://www.discourse.org/). Mostly because it is open source and we have the possibility to keep my so extremely costly generated content in our house and not been hook to any company. At the beginning we are using the hosted version for convenience though.
We are in the beginning of this process (3 months), for now everybody loves it. We are trying to build the habit that every time someone asks something (by email, slack, ...) we ask to create a question in our Discourse and we answer it there.