Why Do Developers Like Wikis?

People write reams of documentation in wikis, where it subsequently rots and gets out of sync with the reality of the code and practices it describes.

Wikis are a fine idea. They are on the web, making them easily accessible to the whole team. They track the history of each wiki page. They make linking to other wiki pages and resources easy.

Wikis are good for documenting practices that apply across projects and across teams, but they fall short when it comes to documenting the code and practices of a single project. When I browse the source code of a project, if all its documentation is on a wiki, how do I find it? I can search the wiki, but even if I find something that looks relevant, my confidence that it’s in sync with the version of the code I’m looking at is near zero. If many projects share a wiki, I’m likely to find a lot of noise from the other projects before I find the signal I’m looking for.

I’d much rather have a README in the top level directory of the source code that tells me how to get started. It should include:

1. where the central copy of the source code lives[1]
2. where the project’s specifications live
3. how to get its dependencies
4. how to make it executable
5. how to execute it
6. some representative examples of things I can do with it once it’s executing
7. how to execute the project’s unit tests
8. how to write a Hello World unit test within the project
9. how to share my changes with the rest of the team
10. how to install the software on shared development systems
11. how to execute integration tests that exercise this project in a larger integrated system
12. how to write a Hello World integration test
13. how to install the software on production systems

Keeping the developer facing documentation close to the code makes it easier for new team members to find, and adds the benefits that you can branch and merge the documentation along with the code, and you can edit it offline in the same tools you use to edit the code.

Nevertheless, there will be some documentation that is both valuable and not specific to any single project. A shared space is a good place for that stuff. But if it were in files on Box or Dropbox, I could use native programs, offline, to view and edit it. Or if it were in Google Docs, I could collaborate with others in real time. Either would be better than a wiki.

Now, if there were a tool that made real time collaboration on common file formats possible, that would be game changing.

[1]: Yes, I already have the code, but don’t assume I got it directly from the source of truth.