Documenting the Documentation Project
enrico at enricozini.org
Thu Dec 30 08:27:41 UTC 2004
On Wed, Dec 29, 2004 at 07:41:25PM +0200, Sean Wheller wrote:
> Many of you will be still dizzy from all the changes recently introduced to
> SVN, so please do read the following wiki page:
Had a look, converted to Moin markup (in the Documentation Team BOF
we decided to go with Moin as a markup of choice), made some small
There are a couple of things that are different from what you write:
- The wiki is intended firstly as an area where everyone can share
informations with the others.
There is no goal to convert all of the Wiki to DocBook: in the wiki
there are pages used by the development team to brainstorm ideas,
meeting notes, pages put up by ubuntu-users at lists.ubuntulinux.org
contributors to post a link instead of a long explanation, and other
things that may or may not be meaningful in a more structured book.
Althought the wiki can indeed be a way for increasing the volume of
material resources for the Core Documentation Project, this is not
its primary goal.
- Not necessarily everything done by the documentation people is
DocBook. For example, one of the things we thought of doing (and
Plovs is on it) is improving existing documentation like manpages,
which are written in troff. We could dump quick HOWTOs or tutorials
in the wiki to share them quickly, and them pick them up in DocBook
or move them to the official website.
It's ok to say that most of the work will be done in DocBook, though,
and that DocBook is the markup of choice for bigger things.
- Another idea for the team is to be a point of entry for people with
no technical skills at all who would want to contribute. Ideally, as
soon as someone is able to type text, they should be able to join the
list and help.
In this case, "You will need knowledge of Docbook" is a bit too much:
I wouldn't mind if someone with lots of passion and no technical
skills could just publish a mail in the list or a wiki page or even
attach an OpenOffice Writer document to a mail, and me or others can
pick it up, convert to DocBook and commit it.
The rationale here is that in the world of Free Software we've always
been saying "if you can't program, write documentation", but we've
often raised the bar a lot for doing that as well. In this case
it'd be nice to strive to keep the bar low.
If we consider the patches that happened in the repository in the
last week or so, we see that we haven't unfortunately been successful
on that yet: lots of patches were for hi-tech cool things that
definitely improved the quality of the work process, but very few
people committed something which is pure text contents.
In this sense, I think the DocBook part should really be split and
linked like "How to contribute with DocBook". I can write a "How to
contribute with the Wiki" and a "How to contribute with just a text
I think that the DocBook+Subversion part would be a really great and
extremely helpful "How to contribute with DocBook" page. It's really
> Next release I intend adding explanation of how the Docbook application level
> hangs together.
> The release after that will include the "Ubuntu Docbook Interchange Protocol."
I'm a bit scared by "Application level" and "Interchange Protocol": they
seem to be names that apply to groups with like 200 contributors. I'd
think twice before adding levels of complexity and abstraction to a
group which is still small: I fear it would scare new people or
suffocate existing ones.
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 189 bytes
Desc: Digital signature
More information about the ubuntu-doc