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

[Jonathan Jesse]

Part of me always wonders why every time we near the end of the release we
start discussing on how we want to change everything.  Just prior to release
of Breezy we had this discussion in regards to is DOcbook the way to go, why
do we ship it this way, is the wiki to hard to understand and follow? etc,
etc, etc

I don't think the wiki is that hard to follow, and let me explain why.....

I started using Ubuntu just at the end of warty, I read about it on
slashdot, downloaded the live cd and thought this looks cool I'll give it a
shot.  I am in no means a Linux guru.  I started out on Red Hat 7 and tried
several version of Slackware.  I also at the time grabbed some books, read
and got my Linux+ certificaiton.
At this point I got involved in my real job, a Windows administrator.  I can
setup Active Directory, configure Exchange to work in a Front End/Back end
config mode, can change things in group policy to enforce the policies of a
company and many other things.  however I will be honest, I still struggle
at times with Linux.  I have had a heck of a time getting my wireless card
to work correctly, which i have done.  I run Request Tracker for helpdesk
tickets on a Ubuntu based box, and I have a pretty decent system.
Along the way everytime I had a problem I turned to two places, one being
the wiki and if I couldn't figure it out, then I used trusty google.  I have
accounts on the forums sites, but have rarely posted questions and only use
the answers when google turns up good results.

Part of thinks the wiki needs just a little better organization and not a
total restructuring on how things are created and I don't think we need to
re-create how we use Docbook to make the documents.  I started out here
creating patches and only making suggestions, now I have the release notes
and About Kubuntu guide set for Dapper.

A lot of what I have learned so far comes either from the Wiki or in the
case of Docbook, copying what someone else has done.  For those people who
have just started contribuing to the docs, did it really take that much
effort to learn Docbook?

Jonathan

-----Original Message-----
From: ubuntu-doc-bounces at lists.ubuntu.com
[mailto:ubuntu-doc-bounces at lists.ubuntu.com]On Behalf Of Stoffers,
Robert LAC
Sent: Wednesday, February 22, 2006 5:13 PM
To: ubuntu-doc at lists.ubuntu.com
Subject: sec=unclassified RE: The value of separating the doc wiki


>  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






--
ubuntu-doc mailing list
ubuntu-doc at lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc