sec=unclassified RE: The value of separating the doc wiki

[Stoffers, Robert LAC]

>  I guess what I am proposing is that the wiki be viewed as the first level of document development and collaboration. The community develops and  
> updates this "unofficial" documentation. Then the core documentation members act like newspaper editors by revising, polishing, and selecting  
> appropriate content for the official documentation repositories. 

 Hi Ross,
 
I've been thinking about this myself lately, the problem with taking docs from the wiki is that they still need to be converted to docbook, usually are not written to the same standard as the docs (there is a style guide for official docs) and the whole process is just a pain in the bud. Lately I have been looking at the Gentoo documentation for ideas, and a few things came to mind:
 
- They use a different kind of XML called "Guide" rather then Docbook. The advantages of this are massive, the code is simpler and more HTML like thus lessening the learning curve and it can be converted to Docbook or any other format also. Linking Guide XML docs is much easier also (no messy xref etc crap). Guide XML is based off a series of IBM developer articles, for more information see http://www.gentoo.org/doc/en/xml-guide.xml - yes I know many of you think this is crack but you really should check it out.
 
- The documentation on the Gentoo website is the latest version of it pulled out of the repo. If you want to view the XML source you can do so just using your browser, which means not having to learn how to use a revision control system and hence lessening the initial entry curve. One can just make a diff and mail it in to contribute. If we were to switch to bzr the Ubuntu docteam could do something similar with a little bit of php/python/shell scripting too.
 
- You can get a printable version of any document by just adding ?style=printable to the URL
 
- There is a lot more documentation on their website, and its much more mature then Ubuntu's (not much we can do about this one though, it takes time)
 
- The Gentoo documentation is quite easy to find on the web site. I think that help.ubuntu.com needs an obvious link on the front page of the Ubuntu website such as a tab. The wiki tab should be removed, help.ubuntu.com should be the central place for documentation, including the wiki (I know this has already been bought up). 
 
Thoughts?
 
-- 
Robert Stoffers
rob1 at ubuntu.com