Comments on: Stop Using Wikis As Documentation http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/ Living in a state of accord. Fri, 21 Nov 2008 16:59:42 +0000 http://wordpress.org/?v=2.6.3 By: Symphonious » Struts2 Documentation http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-81715 Symphonious » Struts2 Documentation Fri, 25 May 2007 23:10:30 +0000 http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-81715 [...] Oh and did I mention that wiki's are a horrible way to write documentation? [...] [...] Oh and did I mention that wiki's are a horrible way to write documentation? [...]

]]> By: Symphonious » Creating Great Documentation http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-56982 Symphonious » Creating Great Documentation Mon, 05 Feb 2007 21:47:06 +0000 http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-56982 [...] you're thinking of using a wiki, see my earlier rant on how wiki's don't tend towards covering all those sections. You should probably also take [...] [...] you're thinking of using a wiki, see my earlier rant on how wiki's don't tend towards covering all those sections. You should probably also take [...]

]]> By: Dissociated Press / Wikis as documentation substitutes http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-44731 Dissociated Press / Wikis as documentation substitutes Mon, 18 Dec 2006 02:12:22 +0000 http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-44731 [...] Interesting post by Adrian Sutton, “Stop Using Wikis As Documentation” where Sutton points out some of the problems endemic to using wikis as a substitute for real documentation: There’s a few problems, first and foremost there’s no organization. Users don’t know where to look for the information they want, it’s just scattered around the wiki. Even when an attempt is made at organizing things, it’s usually done pretty badly - group the how tos to gether, plonk a link to a getting started guide somewhere and maybe a link to one of the install guides. Rarely do you find documentation that guides the user from getting basic information about what the product does through a simple guide to installing and getting started then on to a feature tour with tutorials etc. In other words, the wiki doesn’t guide the user on their learning journey through the product. [...] [...] Interesting post by Adrian Sutton, “Stop Using Wikis As Documentation” where Sutton points out some of the problems endemic to using wikis as a substitute for real documentation: There’s a few problems, first and foremost there’s no organization. Users don’t know where to look for the information they want, it’s just scattered around the wiki. Even when an attempt is made at organizing things, it’s usually done pretty badly - group the how tos to gether, plonk a link to a getting started guide somewhere and maybe a link to one of the install guides. Rarely do you find documentation that guides the user from getting basic information about what the product does through a simple guide to installing and getting started then on to a feature tour with tutorials etc. In other words, the wiki doesn’t guide the user on their learning journey through the product. [...]

]]> By: Adrian Sutton http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-30798 Adrian Sutton Sat, 02 Sep 2006 22:15:18 +0000 http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-30798 It sounds like what's needed is a way to move documentation that was created on the wiki into more formal documentation - cleaning it up along the way. That way content can be created on the wiki by the community and then a smaller group of people who care about the documentation can extract the important parts of that knowledge into the formal manual. They can then identify the missing points and either write it themselves or put a request on the wiki for the appropriate type of content. This could probably be done with wikis today, but I suspect improved tools support would make it much more likely to happen. Such a tool would combine a wiki with a document management system - anyone can edit the wiki and the document management side is more restricted and can pull in content from the wiki. It sounds like what’s needed is a way to move documentation that was created on the wiki into more formal documentation - cleaning it up along the way. That way content can be created on the wiki by the community and then a smaller group of people who care about the documentation can extract the important parts of that knowledge into the formal manual. They can then identify the missing points and either write it themselves or put a request on the wiki for the appropriate type of content.

This could probably be done with wikis today, but I suspect improved tools support would make it much more likely to happen. Such a tool would combine a wiki with a document management system - anyone can edit the wiki and the document management side is more restricted and can pull in content from the wiki.

]]> By: cal http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-30717 cal Sat, 02 Sep 2006 09:37:10 +0000 http://www.symphonious.net/2006/09/02/stop-using-wikis-as-documentation/#comment-30717 I couldn't agree more. I have seen two large adequately documented projects start to use wikis. They both have much more documentation now, but you can never find what you are looking for, when you do find it you are never sure if it is still relevant (you can delete from a wiki....just no one ever does). I shudder every time i point a newbie at the wiki because it's lack of structure prevents and kind of cogent description/picture from emerging. Wikis are great for getting content down as a sort of notes sheet, they need to be backed by a proper structured web site though. If you are going to do just one ditch the wiki and go for a proper documentation site. The best compromise i have see is the php and mysql documentation, well structured but with user content in the comments. I couldn’t agree more. I have seen two large adequately documented projects start to use wikis. They both have much more documentation now, but you can never find what you are looking for, when you do find it you are never sure if it is still relevant (you can delete from a wiki….just no one ever does). I shudder every time i point a newbie at the wiki because it’s lack of structure prevents and kind of cogent description/picture from emerging. Wikis are great for getting content down as a sort of notes sheet, they need to be backed by a proper structured web site though. If you are going to do just one ditch the wiki and go for a proper documentation site. The best compromise i have see is the php and mysql documentation, well structured but with user content in the comments.

]]>