documentation mini-workshop in Oxford [writeup]

[Matthew east]

Hi all,

In this email I will summarise what myself, Henrik and Sean talked about
this weekend.

Process of the Docteam:
-----------------------

Working in the svn repository in docbook xml has many advantages: the
documents are easily portable to html/pdf/pot formats and can therefore
be easily published.

However there is clearly much material and potential for contribution on
the wiki: the question is how to harness this.

The question of a wiki -> docbook process is a difficult one: many have
tried and encountered problems due to the fact that on the moin wiki
there is never a completely consistent formatting: random whitespace can
throw the thing out. Further, docbook has many more tags than Moin, many
of which are necessary for the document to appear correctly (e.g. in
yelp).

Although it is clearly desirable to continue working towards this
process, and to build on the admirable work done by Jeff in the other
direction (docbook -> moin), this should not be high priority as it may
take some time. It can go on in the background. Henrik mentioned he
might be able to obtain some development time on it.

The alternative solution proposed is to:

* identify some documents on the wiki which are considered useful + well
developed, and port them to the docbook repository. This might involve
some of the following procedure:
	1. the documents would need to be identified as ready: we thought that
it would be desirable to have a closed group of people doing this. Such
a group might be the same as the people who have commit access to the
svn repository. However it would be possible for all users to suggest
which documents are ready via a suggestion page.
	2. once identified, the documents could be copied to an locked-down
corner of the wiki to wait to be ported.
	3. there would be a page which listed all such documents, and
volunteers would be able to port these pages into docbook xml manually.
This activity would be a good way to contribute to the team without
necessarily having the expertise to write documentation. It is similar
in nature to the activities carried on by 3 or 4 of us when porting wiki
pages to MoinMoin.
	4. when ready the xml pages would be committed to the repository,
probably into the generic/ folder.

We envisaged that this procedure would be most suited to documents which
do not have a constant flow of change, and would be carried out perhaps
once every release cycle. 

The next question that arises is of what to do with the material in
docbook. This involves the more general question which has been debated
on this list recently about the usefulness of yelp. We suggested that,
as well as publishing the documentation in yelp, the static part of the
website might be resurrected to provide an area to publish the material.
This might be better than the wiki, which does not carry an air of
authority: users need to know what documents they can trust.

Wiki Transition:
----------------

The documentation team will be responsible for the /doc subfolder. This
will contain both pages which talk about the methodology of the
documentation team, and the documentation itself. The transition may
provide a good opportunity to restructure much of the content on the
wiki. Much of the transition may have to be done by hand, given that the
zwiki and moin engines do not easily permit automatic transfer (although
an automatic solution needs to be sought for things like UserPages and
developer pages). This will give an opportunity for restructuring. It
was agreed that there is scope for deleting pages in the transition
(although _with caution_) which might not be useful.

Ok i hope this is a fair summary. Disagreements, comments,
clarifications, questions, suggestions please :)

One that just occurred to me re: the wiki transition: if we start
transferring page now, what do we do about changes made on the current
wiki between the transfer of the page and the final move of the wiki?

Matt
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050523/25feb249/attachment.pgp>