4 ms·
> "Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the time and effort to write some real documentation instead." I simultaneously agre
by zdw 13y ago
> "Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the time and effort to write some real documentation instead."
I simultaneously agree and disagree with this. Wikis fall into two categorys:
1. "If I build it, they will come", which is where the developer who doesn't want to write docs throws one up, and says "hey, all you users, document it on your own, I don't want to mess with it". Then new versions come out, things change, the docs are old/incorrect, and people get frustrated, and nobody end's up using the wiki.
2. People who actually take time to make it into a great site - these are few and far between. http://ipxe.org http://ipxe.org is one example of a well done wiki, but I'm betting that a single person spent a good deal of time doing the site.
Unfortunately, it appears that 95% of the technical documentation wikis out there are in group #1, not group #2.
- solistice 13y agoBut if it's just one person maintaining the wiki, with a few others contributing, why have a wiki at all instead of a centrally curated guide? With wiki like systems, you get noise (in the form of people making mistaken changes, malicious changes, etc.). There's really only two ways you can guarantee quality, which is either the aforementioned person reversing those changes (undoubtedly additional work), or enough people checking those edits, improving or reverting them. But your small to medium size project isn't going to garner enough people to have the latter option work well. And if you have a small group of people that would be willing to do that maintenance work, why not just write some documentation together with them?
- fnordfnordfnord 13y agoI cultivated a wiki for a few years in the hope that someone would come.
- solistice 13y agoIf it will make you feel better, you could tell me the link and I'll check it out.
- fnordfnordfnord 13y agoSorry for the late reply. Thanks for the offer. It was an internal Wiki for my department at a small college. I used it to distribute lecture notes and things to students, and share other resources with other faculty. I also created a space for students to use it for their projects. It is defunct now. I got too busy last year to keep up with it, and haven't replaced it.
- derefr 13y agoWhat do you call a wiki coupled to a permissions system? That is, a CMS where: - every logged-in user is a contributor+editor+publisher and so can just edit-and-post content as if the system was a wiki, - but new users have to be created by some administator, or invited, etc; there's no "Register" link, - and for non-logged-in users, there are no trappings of "wikidom" visible (e.g. recent changes page, sandbox, any revision of posts other than the marked-as-last-known-good revision, etc.) I have a feeling that this is what 90% of documentation projects really want: something that's a wiki from the inside, and a CMS from the outside. Does this design have a name?
- emddudley 13y agoA wiki. You can customize wiki UIs to act exactly as you're describing, it's just that nobody changes the defaults.
- derefr 13y agoYou can customize wikis to make them into MMO games, but then they're not wikis any more. It would be useful to have a name, I think, for this specific thing, because then people who want this specific thing could download software that already provides this specific thing, with no customization involved.
- saraid216 13y ago> You can customize wikis to make them into MMO games, but then they're not wikis any more. That's not necessarily true. I think it'd be interesting to make a religion-inspired MMO game that's about writing and rewriting a holy text. Use a voting system to make something sacrosanct and thus harder to make changes to.
- e12e 13y agoThis. The term "wiki" really just means quickly/easily editable (hyper)text. It's a shame it's sort of grown to mean "text that will magically maintain itself". Just like "just open source it" isn't a solution to library maintenance (but can be a prerequisite for community contribution) - "put up a wiki" doesn't mean the thing will curate itself. I'm reminded of a quote by Cunningham where he says that his most frequent actions on wikis are to delete and consolidate content. Maintaining a wiki takes work. Having an editor, along with a process for going over material regularly (say once a month) helps a lot. That and/or have "owners" for pages and sections (eg: the developer responsible for the gizmorenderer gets reminders to review the example code and documentation for the renderer, while the devops lead gets reminders to review the install/setup instructions etc). If a section hasn't been marked "good" for the past two-three months - have the system delete it. Encourage people to review old documentation/pages when writing new -- maybe update a few old examples and add new ones, rather than just add a single new example that covers the new API etc. Tooling and automatic reminders can help, but at the core what is needed is a (business) process for maintaining the thing -- it can be completely manual -- but it needs to be there.