Documenting the Documentation Project

[Sean Wheller]

On Thursday 30 December 2004 10:27, Enrico Zini 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.

OK.

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

Agreed.

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

Some people, myself included think there is to much in the Wiki.

There was a dicussion to perhaps adopt an approach where content that is 
documentation will move to Docbook and everything that does not belong in 
Docbook would stay in wiki.

An area should still remain where people who are not proficient with docbook 
can have an easy way to add content. However, at present wiki is becoming 
like a dumping ground.

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

Agreed

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

Not Agreed
By its semantic nature Docbook is presentation neutral. Formats such as troff 
are presentational.

I proposal is to move everything to a presentation neutral source, in this 
case Docbook, from which we can derive a variety of target presentational 
formats.
DB XML
 ----> HTML/XHTML
 ----> XSL:FO
 ----> MAN
 ----> Wiki
 ----> etc.
 ----> etc.

As a standard format, Docbook will enable everyone to focus in one place. My 
impression today is that we have people off doing their own stuff and no way 
for other members to have visability or to help. In some instances this 
cannot be helped. For example, Colins' "Installation Guide," it is better to 
keep it upstream. I don't understand Plovs work process, so I cannot say if 
this will be of benefit. What is important, even with the book we have in SVN 
today and no more, is to understand the concepts I will relay to you in the 
next paragraphs.

By having everyone work in Docbook we can all focus our efforts and reuse 
content from these efforts between various initiatives. For example: Let's 
say Plovs writes a killer piece for "netstat" and an Author writing an Admin 
Guide wants to use it. How easy is it today?

Now imagine Plovs wrote in Docbook and transformed his work to manpages 
(Docbook2man), the writer on the Admin Guide can easily use XInlcude or 
XPointer to bring Plovs most excellent piece into the Admin Guide, without 
physically duplicating the Plovs text. Next time Plovs updates the 'most 
excellent' netstat section the Admin Guide is updated.

This type of thinking in our application and process layer can have a 
significant impact of how much we can do with a small team. In my experience, 
writers can focus more on writing new stuff and do less maintenance and brain 
dead 'search and replace' work. Translators need less time for translations 
and so on. Net result, overall productivity goes up and so does consistency 
and quality, all of which have positive impact on the end customer- "The 
User."

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

This document was mostly focused on Core Documentation, which as I understand 
will be *stored* in Docbook format. There is noting to say that people cannot 
write in some other format and submit their work. However, I agree that there 
is nothing that says the can.

In this case perhaps, "You will need knowledge of Docbook" should be "Ideally 
you need knowledge of Docbook, however you may submit content in other 
formats so that other members of the team can port it to Docbook."

The problem with this is that once the document is ported it is easier to 
manage and maintain it in the Docbook source. Should the document maintainer 
decide to do an update, we may find ourselves porting whole documents time 
and again.

For this reason I would like to encourage people to maintain in the XML 
source.

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

Not really, many projects face the same problem. There are very real 
advantages to using XML for publications. My article on this page outlines 
them. However, as we know Docbook ain't easy, so projects still accept work 
in other formats. There is no point rejecting these contributions on the 
basis that they are not in Docbook. Look at other projects, like KDE and you 
will see that they accept other formats but encourage use of Docbook.

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

Are you reffering to my patches. If so, please understand that I found the XML 
sources in their previous state incredibly hard to work with. Not one file 
was valid. Members of the GNOME team have gently repremanded the UDT for the 
flagrant use of Docbook. My patches fix this. In addition they improve work 
process, something that is always positive.

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

Agreed.
All three fall under "How to Contribute."

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

Yes, the section we need is "How to Contribute." Where users will find 
everything they need to get the source, understand how we use Docbook, etc.

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

Actually after starting the "Ubuntu Docbook Interchange
Protocol" I am wondering if I need to do "how the Docbook application
level hangs together."

p.s. Thanks for replying on list :-)

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20041230/667d8d55/attachment.pgp>