Second Documentation Team Meeting summary

Sat Nov 6 17:04:01 UTC 2004

Hello all!

I've finally finished summarizing the meeting we had 2 days ago.  You
can find it on the wiki at https://www.ubuntulinux.org/wiki/DocumentationTeamMeetingSummary2

For the really lazy people that I love and cherish, here's a copy:

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

 * Alexander Poslavsky (plovs)
 * Alexander (Sasha) Wait (asw)
 * Christoph Haas (ChrisH)
 * Enrico Zini (enrico)
 * George Dekavalas (George^Deka)
 * John Hornbeck (hornbeck)
 * Louise McCance-Price (lulu)
 * Paul Sladen (sladen)
 * Sivan Green (sivang)
 * Steven Parkes (sparkes)

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 a
   #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 FAQs 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.

  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.

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!

Ciao,

Enrico

--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20041106/7318ce8c/attachment.pgp>