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:

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

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

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.

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