Documenting the Documentation Project

[Enrico Zini]

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:
> https://www.ubuntulinux.org/wiki/AboutTheUbuntuCoreDocumentationProject

Had a look, converted to Moin[1] markup (in the Documentation Team BOF[2]
we decided to go with Moin as a markup of choice), made some small
changes.

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[3]) 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[4].
   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
   editor".

I think that the DocBook+Subversion part would be a really great and
extremely helpful "How to contribute with DocBook" page.  It's really
good!

> 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.


Ciao,

Enrico

[1] http://www.ubuntulinux.org/wiki/HelpOnEditing
[2] http://www.ubuntulinux.org/wiki/DocumentationTeamBOF
[3] http://www.ubuntulinux.org/wiki/DocumentationTeamCurrentWork
[4] http://www.ubuntulinux.org/support/documentation/helpcenter_view
--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20041230/9ce30f31/attachment.pgp>