Documenting the Documentation Project

[Sean Wheller]

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

Agreed.

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

Agreed.

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

Agreed.
However, there is much information in Wiki that could be in Docbook. At some 
point we will have the HTML version of Docbook online, then we get 
redundancy. Which is redundant? Wiki or Docbook HTML, guess we will discover 
this in the future.

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

Agreed. I would set P1 to publishing definitions, audience profiles, 
expectations and plans behind all documents.

>
> 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 :)

Agreed.

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

OK so let's agree then that we have no need to focus on those documents. 
Although I would have like to have better integration. 

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

OK. I understand. Hopefully now that the Docbook Application level is getting 
stable people will start work. However I don't think it is a good idea to 
start on these documents until everyone has an understanding on the *plan* 
hinted on above.

I think that the split in focus between wiki and docbook is dangerous for 
members of the doc team. Your explanations help to clear matters, however I 
am not sure that the doc team priorities are set correctly at this time.

To get work into the Docbook documents I suggest we:
- publish the *plans*
- split the work amongst us
- commit often
- track issues in bugzilla from the onset


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