4 ms·
Everywhere I've ever worked, "set up a wiki" has meant "create something once that nobody ever remembers the existence of"
by llimllib 9y ago
Everywhere I've ever worked, "set up a wiki" has meant "create something once that nobody ever remembers the existence of"
- philwelch 9y agoBecause writing the documentation is work and seems hard so people don’t do it.
- deleted 9y ago[deleted]
- ebiester 9y agoOr, 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.
- ivan_gammel 9y agoIt's a trained skill - everyone can be a librarian in the team.
- ebiester 9y agoOne 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.
- protomyth 9y agoI 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.
- ghthor 9y agoPro librarian work right here, Nice work!
- davidbanham 9y agoIn my experience, documentation stored in source control alongside the code gets updated and maintained. Documentation stored in a wiki is left to rot.
- philwelch 9y agoFor code documentation, that's definitely true, but you need places to document processes, designs, and other things like that.
- carlmr 9y agoOut 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.
- dingo_bat 9y agoAlso, nobody can ever find again, even if they remember. And then they will create a whole new page for the same thing plus a small addition. Then 6 months later some poor soul will notice that you have 10 pages on how to do X and he will delete everything and consolidate them all into one page. Then the cycle begins again. Wikis are fucking useless.
- user5994461 9y agoEverywhere 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.
- mvindahl 9y agoThe 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.
- user5994461 9y agoBetter have a wiki with some obsolete pages than have nothing and no documentation at all.
- mvindahl 9y agoTrue 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.
- ebiester 9y agoI 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.)