Or, it accumulates so much cruft that it's hard to find the valuable information. I think there's room for documentation librarians, whether by role or job title, but it's hard to justify the expense in smaller organizations.

I found that a bit of scripting will make a wiki a bit more maintainable. Replace pages that are out of date with a tag of some sort (e.g. #outdated). Have a script spider the wiki from the home page and send out an email with all the reachable pages with tags. Either fix the page or make sure it’s no longer reachable.

Pro librarian work right here, Nice work!

It's a trained skill - everyone can be a librarian in the team.

One person needs to lead the standards and the organization or the conflicting opinions will drive it apart. The librarian is a role, but that doesn't absolve the rest of the team from following the librarian's lead.

In my experience, documentation stored in source control alongside the code gets updated and maintained. Documentation stored in a wiki is left to rot.

For code documentation, that's definitely true, but you need places to document processes, designs, and other things like that.

Out of sight out of mind is one component of this. The other is how easily you find the documentation. Most people are willing to document if it's easy to do so, and most people will read the docs if they're easy to find.

Everywhere I've worked with wiki, I found that people actually read the wiki and that it contained both important guides for new users/developers/maintainers and old documentation that was crucial for old systems.

The last three corporate wikis that I have worked with have tended to contain some very useful and well maintained sections detailing stuff like developer machine setup and tooling.

They have also contained large amounts of information from separate projects, none of it which was relevant to my task at hand, and on top of that they have contained a wasteland of obsolete pages, the contents of which was trusted by no one.

I don't have a problem with the concept of a Wiki per se but I do have issues with treating them as a magical virtual haystack on top of which you can shovel information and from the midst of which you can painlessly extract needles.

I swear there's a startup in there... I have some ideas to combat it. It will probably rattle in my brain for another year until someone has already come up with a "good enough" solution and I'll lament that I didn't go for it.

(Life circumstances have me away from the startup life at the moment.)

I think that if search worked, the Wiki could be a great hub of information.

For the search to work, it should make an effort to get to know you, that is, try to track which pages you have previously edited or opened, or maybe it could access information about which project you are currently assigned to in JIRA or which internal repositories you have recently committed to in git. Also, which pages are popular, which pages are mainteined, etc. This would enable its search engine to filter bubble you and provide far better results that I currently see Confluence doing.

Further, it should be able to contain pages which are just indexed mirrors of other resources. Some pages could be simply uneditable mirrors of markdown files in your repository, making it possible for developers to keep documentation alongside the code if this makes more sense to them. Other pages could be mirrors of Word documents or Excel sheets of PDF files on shared drives or where the company likes to keep this stuff. All of this stuff would be thoroughly indexed by the wiki and would show up in search results.

So I guess what I'm proposing is that wikis become an aggregator of information more than a single store of information. And that they really, really nail the search part.

You've essentially described pagerank. Pagerank's patent just expired. Hopefully, that means it will start appearing in wikis.

Yeah, I probably did. The "personal filter bubble" thing is very much how google does it. I don't know the details about pagerank but I imagine that they are constantly tweaking their secret sauce to increase revenue and that they would rather keep the juicy parts secret than having them described in details in a patent. Also, I'd imagine that other search engines, such as Bing, have developed similar algorithms although I'm sure thay take great care not to infringe upon the pagerank patent.

Disclaimer: Purely conjecture on my part. No particular knowledge of patent law, and only a high level understanding of the pagerant algorithm.

Better have a wiki with some obsolete pages than have nothing and no documentation at all.

True dat. Writing no documentation is also a bad path.

Personally I've come to favor keeping the technical documentation close to the code. That is, keep it as markdown files and check it into git. They are just as easily hyperlinked to as a wiki page on the bitbucket web interface (or whichever system is used). The main README.md should contain information on how to set up the dev environment. Other README.md files, located in the folder root of modules, provide more specific information.

Documentation of a less technical nature may still find a natural home in the Wiki, since we also need a place where various managers, testers, salespeople, support people, etc. can maintain their documentation.

Because writing the documentation is work and seems hard so people don’t do it.