> -----Original Message----- > From: Dan Diephouse [mailto:[EMAIL PROTECTED] > Sent: Friday, September 08, 2006 12:14 PM > To: [email protected] > Subject: Re: Wiki and Web > > > > Johnson, Eric wrote: > > >Dan, > >In terms of developing a Web site, and documentation, it appears we are > >coming at this from different points of view. From my point of view as > >someone whose focus is on documentation, messaging, and Web design > >taking an hour to polish up a Web page or a piece of documentation is > >not an egregious burden. I would imagine that you spend as much effort > >testing the code base before releasing it. A professional Web site > >should not need to be updated on a daily basis. It, like the released > >version of a product, should be well tested and reviewed before being > >published. This does make it more difficult to make updates to the site, > >but it also ensures that updates are well thought out and vetted before > >being made. > > > > > I disagree. First, I don't actually believe that this is how > documentation is created. Often a release is pushed out and then > documentation is written. Documentation has a life of its own beyond > just the initial release.
Having worked as a doc writer for a number of years, I have never seen a release pushed out with out documentation. The documentation often does get improved after the initial release, but it is solid before hand. My experience is entirely based on working for a company that wants to sell software, not an open source project however. > Second, I am of the philosophy that documentation should be part of the > continuous improvement cycle of the project and it is impossible to > separate out from developing and support of users. For instance, with I > read the xfire user's list and a question comes up that isn't addressed > in the docs, I go and write something, then point users to it. Or I > write a response and ask users to add to the docs. (a lot of times they > even do a really thorough job). > > I think the wikipedia provides a great example. It goes through > continuous improvement and people watch it religiously for any > backtracks. This makes documentation much more agile and makes it much > more open/approach to others. I too think that documentation is an ongoing process and as people come up with new issues, use cases, and other suggestions for improvement the documentation should be updated. I also like the idea that any user can add information about the product. However, I also think that you need to have both a place where user supplied information can live and a separate place where documentation that has been reviewed, vetted, and given an official stamp of approval lives. Most teachers I know would not accept Wikipedia as a valid reference for information simply because it does not have a strict review process. I'm going to go out on a limb and guess that most major companies, who we hope are going to use CeltiXfire, are not going to accept documentation that is on a wiki as sufficient. > > >The same would go for versioned, official documentation. The source > >should be stored in the project trunk with the code and built as part of > >the project. When a version of the product is released, the vetted and > >reviewed documentation can be packaged and delivered as part of the > >download. It can then also be pushed out to the Web site. > > > > > I disagree that documentation should be so strictly version with the > project as it often continues to improve outside of the release cycle. > Docs are never done. > How do you keep the documentation aligned with releases? What if an outside entity, such as IONA, wants to consume and repackage the documentation for a particular release? > >This does not preclude a developer from documenting a new feature, or > >adding supplemental documentation, through the wiki. In fact, that is > >probably the best place for it. > > > Why is that the best place? It is outside the normal docs and harder to > find, > It does not have to be harder to find, but it does mean that it is clearly placed outside of the official set of documentation. > >If the community feels that information > >on the wiki should be moved into the official documentation, then a task > >can be submitted and the work can be done to make that happen. If not, > >then it can stay on the wiki. Links can be added to the main page to > >make such forms of documentation easily accessible. > > > >Here is what I propose: > >1. The main Web site for the project is done in HTML. This means anybody > >with HTML knowledge can make updates. > >2. The Web site is only republished when there is a need to update it > >and the community, or an elected member of the community, has reviewed > >the content. > >3. The main Web site has at least one link to the Wiki where people are > >free to add FAQ's, documentation, and other stuff. If something there > >meets muster, a link to it can be added to the main site or the content > >can be ported to the main site. > >4. If project members have blogs or other links they want published > >those too can be added to the main site if the community thinks it is > >appropriate. > >5. Official, versioned documentation is written using DocBook XML 4.2 > >and the source is stored in the trunk along with the code. > >6. The official, versioned documentation is built along with the code > >and is part of the official product release. > > - There are open-source XSLT stylesheets that can be used to build nice > >looking, customizable HTML and PDF output from this source. > >7. Other documentation can be written on the wiki. If the community > >thinks it belongs in the official set, it can be ported. > > > > > I've thought long and hard about this, but I'm -1. I think we should do > it all in the wiki. Many projects do it (for instance Dojo uses JotSpot) > and it works very well. I think doing it all in the wiki is more > inclusive, agile, and community focused. All in all I agree that a wiki is a great way to encourage community contribution and provides a fast way to get content produced. However, they also present problems such as versioning, image, structure, indexing, navigability... Once you get beyond a few bits of documentation, a Wiki can get cumbersome to navigate. They also, in my opinion, lack a certain amount of credibility and professionalism. The Apache Web server and Tomcat don't use wikis for their docs and I doubt their users would be pleased if they decided to switch to a wiki. > > Cheers, > > - Dan > > -- > Dan Diephouse > (616) 971-2053 > Envoi Solutions LLC > http://netzooid.com
