= Minutes of the third Documentation Team Meeting =

The meeting's details and agenda can be found on DocumentationTeamMeeting20050312.

The Third Ubuntu Docteam Meeting started at 22:10UTC.

Active participants:

|| '''Nickname'''    || '''Full name'''        ||
|| enrico      || Enrico Zini      ||
|| froud       || Sean Wheller     ||
|| jeffsch     || Jeff Schering    ||
|| trickie     || Nick Loeve       ||
|| Burgundavia || Corey Burger     ||
|| drasko      || Drasko Draskovic ||
|| ogra        || Oliver Grawert   ||
|| dholback    || Daniel Holback   ||
|| Liz         || Liz              ||
|| mdz         || Matt Zimmerman   ||
|| Mithrandir  || Tollef Fog Heen  ||
|| Riddell     || Jonathan Riddell ||


Three main topics were in the agenda:

 1. Clarification of recent events
 2. Releasing Hoary
 3. Post Hoary


== Clarification of recent events ==

=== Disagreements ===

I these few lines speak by themselves:

 * '''trickie''' i posted the first topic on the wiki, because i was not understanding what was going on very recentyl in regards to the team
 * '''enrico''' We can start with the first one, just quickly I'd say: we seem to have reached harmony, and I don't want to shake it too much :)
 * '''froud''' basically Burgundavia and I kissed and made up
 * '''Burgundavia''' right
 * '''trickie''' love is in the air...
 * '''Burgundavia''' well I am single
 * '''trickie''' ha ha ha
 * '''enrico''' * enrico hugs Burgundavia 


== Releasing Hoary ==

=== Phases of documents ===

Sean Wheller proposed some guidelines to contributions at various develoment stages;
enrico agreed we've been needing some freeze, or half-freeze, for quite a while.

Jeff Schering initially proposed "planning, writing, editing, release".

Sean said that he normally uses "outline, first draft, second draft, camera
ready", with this rationale:

 1. from outline we can derive status docs and allocate work between us
 2. after each decides on a section we prepare first draft collectively
 3. then we switch sections as we go to second draft each checks and edits the other
 4. after second draft we do technical review at which point major edit should be limited to technical error, punctuation, spelling, grammar

There was consensus that, as Nick said, "if someone sees something they would
like to change (majorly) but it is already in final draft, then they should
line it up for the next release".  Sean noted that quality and quantity is
built over the course of several releases.


Enrico was worried that for the "switch sections" part to be effective, we
would need a strongly coupled team, which would not be easy due to the more
open nature of the group, and proposed a variation:

 1. "Wiki mode": everyone adds contents and comments everywhere
 2. "Style mode": people pull the contents of a section together in a nicely readable way, giving them a narration and a consistent meaning and style
 3. "Review mode": major edit should be limited to technical error, punctuation, spelling, grammar
 4. "Ready for release"


The discussion moved on before one of these proposal had been agreed on somehow.



=== Status of the Quick Guide ===

It is about time to declare the QuickGuide in a review-only phase.  Only the
BitTorrent section needs finishing, and Corey Burger offered to write it.

With regards to translations, Nick sent Enrico a .pot file with the QuickGuide
contents, to be forwarded to the translator team.  Enrico fowarded it to Carlos
Perelló, which hasn't gotten back to him yet.  Nick is also looking into how to
build a translated DocBook from the translated .po file.


=== Getting feedback from the developers ===

In the review phase, we need review from the developers.  On the QuickGuide,
but much more so when we will have an User's Guide or the Admin Guide.

At the moment, Jeff Waugh (jdub) is reviewing the QuickGuide, and we should
ping him from time to time to ask how it is going.  Oliver also suggest to drop
by in #ubuntu-motu and call for help.


==== Telling the developers what needs reviewing ====

We discussed how to include the developers in the review process and save them
time.  Mainly, how to give them specific reference to what they should check.
Nick confirmed that developers' feedback for the release notes was good, but
because he asked for general review and comments, it came in over a few weeks.

Sean proposed to:
 1. Give J.Random Devel an [[http://www.zvon.org/xxl/XPathTutorial/General/examples.html|XPath]] pointer to the sections we would like him to review.
 2. J.Random Devel does (or updates) a checkout from the subversion repository
 3. J.Random Devel checks the referenced XML node, adds <!--comments--> or directly edits the text.
 4. J.Random Devel sends us the output of "svn patch"
 5. We get the patch, fix the style of the edits if the devel did not have time to mind about it, then apply it.

Sean then wondered how to know if developers are ok with this process.  Oliver
Grawert said "probably", but reminded that the developers get busier and busier
as the release date approaches.  Corey noted that we only need one check from
the developers at the beginning of the review phase, as after that there will
not be any new stuff going in.

Enrico summarised the deadline problem this way:
 tricky thing is, the more we approach release, the more we need reviews from the devels
 however
 the more we approach release, the more we have to do without the devels

Nick proposed to have something on the web, that wraps the current doc
previews, and allows the devs to leave comments there.  Enrico noted that
unfortunately, there is no good system to annotate webpages yet, even if we all
would use it.

Enrico wondered what is an easy way to generate XPath pointers to specific
sections, and an easy way to open a document and jump to a given XPath.  Sean
proposed to make a short XPath tutorial.  Nick proposed to add XPath pointers
in the status reports for all sections marked with a certain status.

Enrico pointed out that the risk is that if a developer has to spend some time
figuring out how to get the text out of our pointers, he would tend to slip
reviewing lower in his/her overfull TODO-list.

In the end, the consensus was on trying with XPath, and if it does not work,
negotiating the best way with the developer(s) involved in the review, on a
case-by-case basis.

=== Open bugs needing to be solved for Hoary ===

'''[[http://bugzilla.gnome.org/show_bug.cgi?id=170074|Yelp's XRef problem]]'''

We discussed about it a bit, Corey offered to add more informations and
screenshots to the bug reports, but before the end of the meeting Tollef
posted the patch to fix the bug:

 * '''Mithrandir''' change {{{/usr/share/xml/gnome/xslt/docbook/html/db2html-xref.xsl ; <xsl:apply-templates select="key('idkey', $endterm)" />}}} to {{{<xsl:value-of select="key('idkey', $endterm)" />}}}
 * '''Mithrandir''' If somebody can verify that it DTRT (Does The Right Thing) for them, I'd appreciate it.

Hooray for Tollef!!


'''[[https://bugzilla.ubuntu.com/show_bug.cgi?id=6899|Our documentation does not appear in Yelp's front page]]'''

Jeff Waugh is working on it.  However, he is very busy and he needs being pinged about it.


'''[[https://bugzilla.ubuntu.com/show_bug.cgi?id=7127|FAQGuide is related to Warty and not on sync with upstream]]'''

Enrico wrote to Chua Wen-Kiat a couple of times, to get the FAQGuide in sync
and coordinate on updates; however he did not get an answer yet.

Another problem of the FAQGuide is that some of the answers in it are not the
best ways of doing things in Ubuntu.  Oliver complained that when he was doing
a lot of support in #ubuntu, it would happen that he had to fix the broken
systems that resulted from following the guide.

We decided just not to include the FAQGuide in Hoary for now.


== Post-Hoary ==

=== Desktop-neutral documentation format ===

There are Gnome-specific extensions to DocBook (such as ghelp:*) that make it
harder to process our documentation from outside of Gnome.  Everyone would like
to have documentation desktop-neutral, at least in the format of the sources.


=== KDE QuickGuide ===

Sean and Riddell are interested in having a QuickGuide covering KDE
applications.  Riddell proposes to add KDE-specific parts in the document, then
choose at render time to generate a Gnome QuickGuide or a KDE QuickGuide.

Everyone liked the idea.

This week, the Kubuntu team will also stabilise the application set for Hoary.


=== FAQGuide ===

Many people are interested in updating and fixing the FAQ Guide, bringing it
up-to-date with Hoary and changing troublesome parts to use the Ubuntu way of
doing things.  Corey offered to lead this effort.

Sean proposed to convert it in DocBook FAQ format.

Enrico would like to hear from Chua Wen-Kiat before starting such an effort,
and coordinate with him.


=== Involving Support people ===

Oliver suggested to get the people doing user support more involved into the
docteam.

Enrico said he did not know there were people doing user support, and strongly
agreed with Oliver: the Docteam can help support (for example, producing
relevant RosettaFAQ) and support would help the docteam (for example, providing the
list of relevant questions and topics to work on).


=== Better web presence for the docs ===

Corey suggested to try to have a better web presence for our documentation.


=== LearnLinux with Ubuntu ===

Sean announced that he is working on customizing [http://learnlinux.tsf.org.za
Learn Linux] documentation for Ubuntu.

Sean is also working on a [http://computerdictionary.tsf.org.za computer
glossary database], as a fork from the TLDP Linux Dictionary.


=== Translation support ===

Nick suggested we need a translation support policy; however this has not been
discussed further.


=== Style Guide ===

Jeff Schering wondered if it is still too early to think about a style guide.


=== Editing upstream documentation ===

Enrico would like the Docteam to be able to contribute to upstream
documentation.

Sean said that that is still very problematic to do.


=== After the QuickGuide ===

Enrico was concerned on not losing our good rhythm after the QuickGuide is
almost completed.

Sean to suggested to continue with either the FAQGuide, the AdminGuide, the
UserGuide or LearnLinux.

Nick would like to work on the Admin Guide, and to help Enrico in getting the
translations working.


== End ==

The meeting finished at 23:50 UTC.

The quality has been incredibly high!

Thanks everyone for being there or for reading the minutes.
----
CategoryDocteam