DocumentationTeamMeetingSummary2

DocumentationTeamMeetingSummary2

Documentation meeting summary, thursday november 4, 2004

Let the Holy Cow Moo!

Today #ubuntu-meeting hosted the second Ubuntu Documentation meeting, and this is the traditional summary of the event. The agenda for the meeting is currently found on http://www.ubuntulinux.org/wiki/DocumentationTeamMeeting

Participants (alphabetically sorted):

Cristoph Haas and George Deka have been welcomed in the team.

Status of the team

The meeting started by wrapping up the state of the documentation team: who's who and who does what.

Alexander Poslavsky (plovs)

Have been cleaning up the wiki, adding some icons and looking at the FrontPage

Alexander (Sasha) Wait (asw)
Recently self-apoointed free software zealot. Willing test-subject for community procedures and evangelist for the use of the Ubuntu O/S in science. Also runs an ALife group in Boston and is the new maintainer of the REC.GAMES.COREWAR FAQ.
Christoph Haas (ChrisH)
New to the devel side of Ubuntu. Sent an introduction to ubuntu-devel@ yesterday. Have been maintaining Debian projects like mentors.debian.net before and want to check if there is work for him here.
Enrico Zini (enrico)

Enrico is currently half-available, in Brasil for a conference until the 8th of november. He's been appointed as the documentation team secretary and is now working on setting up himself in this role and to learn how to interact with Canonical. He's the person to complain to. The http://www.ubuntulinux.org/wiki/EnricoZini wiki page lists a list of advertised secretary services.

George Dekavalas (George^Deka)
Currently doing nothing, has been thinking about making the plunge into contributing back and tonight is just the start of it.
John Hornbeck (hornbeck)
Hornbeck is setting up a subversion server in a machine he owns, to be used by the documentation team to do group work on bigger docbook documents. There's been some svn/arch/bazaar discussion; Lulu suggested that Robert Collins would help in setting up Bazaar. In the end, Hornbeck is taking care of setting up the system, possibly checking with Rob Collins about the current status, pros and cons of Bazaar. The idea is starting with whatever works and be open to move to something else if we'll see it would help. enrico and asw offered to help
Louise McCance-Price (lulu)
Responsible for the Canonical and Ubuntu websites and making sure our Community's needs are met by the site and the wiki. Also - have been working with plovs on the APFrontPage
Sivan Green

Has a list of current activities on http://www.ubuntulinux.org/wiki/DocumentationTeamCurrentWork Currently also paying special attention to new people who join us, as well as well as devising a more formal plan / page for that matter.

Steven Parkes (sparkes)
He is writing a book different from hornbeck's, based on the current upstream docs.

Ben Edwards dropped out of the team for reasons that he doesn't want to make public. We all hoped that everything is allright and that he will like to come back: Ben, you'll be really welcome at any time!

In order to see who does what in the wiki, and to avoid spending time making the list in the meeting, everyone could maintain in their personal page in the wiki a list of the wiki pages they maintain.

Group work infrastructure

List of tools we are currently using

  • The Wiki
  • The upcoming Hornbeck's version control systems for large docs
  • The mailing list
  • IRC, currently using #ubuntu-devel. There's been consensus on creating an #ubuntu-doc channel. Enrico is taking care of solving the issue of channel ownership

Since ZWiki allows choosing different markup styles, we tried to see if there should be a wiki markup format of choice. Consensus was that the people active on a page are the ones that decide on its format.

The markup of bigger documents maintained outside of the wiki has instead been agreed to be DocBook-XML (http://www.sagehill.net/docbookxsl/ http://www.docbook.org/tdg/en/html/). ChrisH offered to help with providing Docbook-XML templates and Makefiles

Current wiki issues

Speed
Lulu wrote to the list saying that they're working on it, but nothing is going to happen in the short term
Things lacking since Moin

Enrico has seen TableOfContents often mentioned in the list; noone mentioned other things

License of wiki contents

The documentation team has agreed on GPL; Canonical has to decide. Enrico summarized the issues in https://www.ubuntulinux.org/wiki/WikiContentLicense and Lulu will take care of getting Canonical to decide on it and will get back to the team. One a decision is taken, the license should be mentioned in the frontpage and in the wiki editing page, if possible.

Approaching new members

Sivan is working on a document streamlining the process of joining the documentation team, together with a newcomer TODO list and learning resources.

Various people reported problems joining existing communities, and we don't want to repeat the same mistakes. Discussions and suggestions have been summarized in the Documentation Team Dogma:

Documentation Team Dogma:

All help mails should be answered
Because getting an answer to a mail is very frustrating.
RTFM is not an answer
unless it's nicely put and with a working link to the documentation. If someone is able to RTFM without a link to the M, probably (s)he wouldn't have asked in the first place.
If you see it, reply
This is a nice way to avoid everyone thinking "I'm sure someone will reply to this", with the result that no reply get out.
Don't worry about duplicate replies
It's not a problem if more people answer the same question: for people asking, the more replies the better, and it makes you feel really wanted and that people are there to help you out. And it's not a big bandwidth waste anymore like in the very old days.

Ideally, when someone approaches us and says "I wanna help" he should be able to do so in matter of hours.

George^Deka also pointed that there is no link from ubuntu mail-list page to the -doc ML, and he had to find the link to the -doc list it in a post from -users. He also pointed out that the meeting announcement forgot to mention the channel is on freenode.

Sivan offered to be responsible for the Welcome team, but he would like some backup persons in case he can't be responsive for a while. Enrico offered to help.

Goals for Hoary (HoaryHedgehog wiki page)

Adapt Debian documentation to Ubuntu

The team finally agreed that Ubuntu documentation be based on Debian documentation. Existing Debian documents can be polished and documentation about Ubuntu specific quirks and features should be added. Fixes will be contributed back to Debian.

Ideally, we could use a branch and merge system like the Ubuntu developers do tracking Debian code, but we'll think about that when we get experienced enough with revision control.

Hornbeck will fire up his version control server by uploading gnome2-user-doc into it. sparkes_x is also currently fixing debian docs.

Hornbeck has been talking with people in the Debian Documentation Team (http://www.debian.org/doc/ddp) and they welcome cooperation between the two teams. Everyone has cheered happily at this possibility of joint-work between Debian and Ubuntu documentation teams!

An idea that has shown up in the meeting is also working with the documentation team to improve the documentation that is currently shipped inside packages, like manpages or /usr/share/doc documentation.

Hornbeck will start looking at debian docs that could help us and updating them.

sparkes suddendly dropped the group protesting because he has always been proposing this and noone seemed to care. Everyone was stunned and hopes this was just an outburst of frustration due to some communication problems, that can be overcome soon and we would like to have sparkes back with us.

Package the wiki documentation so that it is readable offline

There is a lot of good documentation, like the RosettaFAQ and HOWTOs, on the wiki that can be useful as help in the documentation, possibly also in Yelp; the doc section in the main site is a mix of HTML and structured text and will need to be all converted to structured text.

Lulu is looking into Plone ATContentTypes and lingua plone for the site so we can deal with translations, but it's going to be a little while to get that done.

Other notes

In the HoaryGoals page there are some doc-related points that is worth looking at.

Another meeting will be scheduled in a couple of weeks about more precise outlining of milestones, with the idea that it's best to talk about milestones after all the infrastructure is in place and we get going writing documentation together.

One other problem with Hoary specific milestones is that the Hoary feature list is stabilized fairly late.

George^Deka will take care of joining the ubuntu-devel list and interact with the developers to help with prioritising documentation work and ask about what they might require.

Lulu proposed to make a page in the wiki with a table with person responsible and deadline dates. Sivan will break up the /USB pages into that, but needs help in doing it. This way each release can have its goals set out by the doc team and the dev team can collaborate with doc team on it.

George^Deka could also try to work on a document on how to make the most out of FireFox, as he heavily follows the Mozilla community.

Hornbeck will be compiling his book into its order of the next couple weeks and calling on people to help in areas.

FrontPage

Plovs has been working hard on the new FrontPage for the wiki, and the data from the old front page has almost all been incorporated in the new one. Everyone agreed this this new page is great and lulu will take care of making it become the new FrontPage Only thing to add is the wiki licensing issue once it will be settled.

Endnote

The meeting finished after 1 hour 45 minutes with the Insightful Moo of the Holy Cow. It's been a great meeting, and see you all in ubuntu-doc and #ubuntu-doc!

CategoryDocteam

DocumentationTeamMeetingSummary2 (last edited 2008-08-06 16:29:50 by localhost)