Documenting the Documentation Project

[Enrico Zini]

On Thu, Dec 30, 2004 at 02:31:58PM +0200, Sean Wheller wrote:

> >    There is no goal to convert all of the Wiki to DocBook: in the wiki
> 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.

I think we're talking about too many things at the same time, here.
I'll split them:

 - wiki for non-documentation things
   we need it, we all agree, ok.

 - wiki for documentation
    - as a dumping ground
    - as a collaborative editing for documentation
    - as a publishing area
    - used by the docteam
    - used by other people

A wiki is probably a dumping ground by definition, and in many cases
it's useful to have such a dumping ground.  For uses by people who are
not part of the docteam (such as ubuntu-users at lists.ubuntulinux.org
contributors), it's really important to have it, exactly as a dumping
ground for the little pieces of documentation they want to share with
each other.
As a documentation team, what we can do in this case is just keep track
of what's there and write some index pages.  This is basically the
reparenting work I've been doing with the HOWTOs.  Other things we can
do is trying to make the wiki easier to use, like plovs has been doing
in writing the HelpOnEditing pages.

If instead we talk of the wiki as a collaborative editing tool we use as
a team, then we all agree we want subversion and docbook instead, and
that's what we are using.  AFAIK, noone's using the wiki to prototype
parts of the User's Guide or the Quick Guide.

We also have the wiki as a source of informations.  Being able to go
through the dumping ground picking up working pieces and using them to
build something is a great opportunity, however we need to pay attention
in not building something which is just duct tape sticking together
parts from a dumping ground.  The documents in the repository have a
clear plan behind (although it hasn't been really made public yet, and
people only know it because they were around in past list discussion).

Well, this all probably just means that we agree in principles, and that
I just suggest that you phrase the document in a less all-or-nothing way
to leave space for the other various cases :)


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

This is already agreed for whatever documentation we create from
scratch.  We can't use DocBook, however, for documentation that already
exist upstream and we just improve or rebrand.

For example, plovs said he would look into existing manpages trying to
give them some love.  In that case, he'll need to work with whatever
format upstream uses for their manpages.


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

So we agree here, too :)


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

No, I wasn't especially referring to your patches.  I was more referring
to the lack of patches that add contents, which means that we've been
fairly bad in attracting active non-technical people, or else we'd have
lots of commits which carry text instead.


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

:)


Ciao,

Enrico

--
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/17349711/attachment.pgp>