[doc] Documentation meeting summary

Fri Oct 15 14:46:52 CDT 2004

Hello!

FEAR THE [doc] TAG!  The Documentation team has arrived!

Today #ubuntu-meeting hosted the first Ubuntu Documentation meeting, and
with this summary of the event we officially unveil the effort that will
put traffic signs on the road to Total World Domination.

Participants (alphabetically sorted):

   Alexander Poslavsky
   Alexander Wait
   Colin Watson
   Enrico Zini
   John Hornbeck
   Mako Hill
   Sivan Green

   Mentioned but not present: JohnLevin, BenEdwards, KevinWixted

After a short presentation, we collected some links on work that has
already started:

   http://wiki.ubuntulinux.org/DocumentationTeam
   http://wiki.ubuntulinux.org/UDP
   http://wiki.ubuntulinux.org/DocumentationArea

The meeting then went on with some brainstorming about the scope of the
team, licensing, formats, philosophy.  Licensing and formats notes are
extracted, summarized and posted later.

 - We are not going to have our own docs for everything: it would be
   disrespect for all the good work that already exists; it would be
   lots of work to do; it would disconnect us from the rest fo the
   community; it would be bad, like, say, total protonic inversion.
   Everyone was clear in this respect, so we strongly disagreed together
   to bury this possibility once and for all.

 - Doc should be handled similar to packages: keep ubuntu-specific
   changes, but base on upstream docs.  We could even use the same tools
   for it.

 - Ideally, there should be no documentation at all.  Programs should
   just work, and do what users want.  Documentation comes in when
   programs are not that clear, or when the users don't know what they
   want

 - One line of working would be see what's unclear in Warty, then check
   if it's been either fixed in Hoary or if it needs documenting Working
   based on what the issues are will also allow us to produce
   documentation which addresses what users are actually trying to do

 - Ideally we should probably follow this to start up a bit:
    1) Identify the goal our users might want to accomplish.
    2) Investigate current works to see relevancy and suitability.
    3) See how we might carry on them, to produce ubuntu compatible
       education.
    4) Establish channels and formats for dissemination of the
       documentation

 - I see we're having two identities here: from one side we have frenzy
   in the hands and we want to *write*, and from the other we are into a
   designing phase for the work On these two identities, both are
   important, and one kills the other

 - see what existing issues there are right now.  Start with docs that
   will address those issues 
   or
   given the issues, see what documentation is around and see if we need
   to produce something new, point to something existing, produce a
   short doc that points to something existing "for knowing more"

 - asw is interested in documenting specific subsystems (eg hardware
   accelerated 3D), GNU Arch for developers, maybe TeXmacs... in general
   he's interested in working on "Ubuntu for Scientists"

 - Enrico has been working on a draft long-term plan which is soon going
   to be posted for comments

 - There has been some discussion between Enrico and Sivan about
   possible titles and topics for ubuntu-specific guides, taken from the
   list in UDP wiki page

 - < hornbeck> enrico: I think we should shoot for this
   http://www.gentoo.org/doc/en/index.xml
   < hornbeck> enrico: they have docs for just about all issues I ever
   ran into for gentoo
   < enrico> Well, the idea is that you should never run into an issue
   with Ubuntu, and we focus on showing how to do creative things
   < enrico> I wouldn't mind finally taking Linux out of the
   troubleshooting and customization and finally into the "how to remove
   the red eyes to your digital camera pictures"
   < Kamion> (enrico raises a good point; please don't document
   workarounds for problems that you should be telling us to fix
   instead)

 - It would be very useful to have a wiki->docbook gateway (based on
   people's pref for doc book) so that works that start in the wiki can
   easily become docbook documents when they grow enough

 - One short term goal could be a short document to get people to
   install ubuntu and connect with the community

 - We would need some sort of docbook primer like the fedora-people use
   (or we can use theirs)

Licensing

   There has been discussion on what license to choose for the
   documentation we produce.  GFDL and GPL have been proposed.  GPL
   would be tricky (you need to include in the source code the preferred
   source for modification) but an interesting challenge; GFDL would
   make it difficult for us to contribute our work back into Debian.

   Some advice will be looked for from sabdlf or whoever has voice in
   this.

Format

   There has been discussion about what format to use for the
   documentation we produce.  We have talked about three different
   scenarios:

    - Documentation we modify
    - Documentation we produce from scratch
    - Documentation items we post in Plone

   For the documentation we modify, we just adapt to the format that
   has been chosen upstream.

   For the documentation we produce from scratch, docbook has been
   agreed as a good default choice.  However, docbook should not become
   a barrier that keeps contribution away, so we should encourage
   docbook but accept contributions the way they come.  We can, of
   course, offer help in learning and converting existing documentation
   to docbook.

   For the items we post in plone, it would be interesting having
   something to help converting plone to docbook, so that if we want to
   aggregate things from Plone into a bigger document we can easily do
   so.  Also, a conversion from Docbook to Plone may help in posting
   back the resulting aggregated material.

   Colin suggests to look at the way the installation manual's done for
   an existing piece of docbook with a build system included.

   The possibility of using a version control system for bigger projects
   is also very important.

Phylosophy mantras

   Enrico posted three mantras that produced enlightenment in one of the
   participants:

   Mantra #1:

      "Do things that are technically simple, and socially complex"

                                (Alberto Gistri, LUGCamp, Bracciano)

      (or else, when even socially simple things happen, you'll be busy
       working at technically complex things)
      (and we already have lots of good developers working at the
       technically complex anyway)

   Mantra #2:

      "Cool thing!  Let's put it into the TODO-list for the
      next-to-the-upcoming release!"
				(Everyone, Warty Conference, Oxford)

      (or else, the upcoming release we're working on right now will
       never happen)

   Mantra #3:

      "First, get to do it.  Then, document how to do it.  Then,
       automate it."
                     (Custom Debian Distributions Meeting, Florence)

      (changing the order produces bad result.  Of course, one can
       reiterate the process multiple times)

   "Automate it" could also mean "send a wishlist bug to the
   developers", and that's one way of having feedback from the community
   to the developers.

   Part of our job will also be to let the developers know when
   something is too complex.  This also avoids us to be busy writing
   documents that should not be written in the first place.

Further work:

 - Enrico will post the proposal draft he's been working on up for
   comments
 - Enrico will post the list of possible documents we could start
   writing
 - A 'documentation' package should be created in bugzilla to act as a
   shared todo-list and collect requests from users.
 - plovs intends to write some documents about kernel compiling,
   possibly starting from http://wiki.ubuntulinux.org/KernelHowto
 - We are going to ask "upstairs" about licensing policies
 - aws has offered to start a "ubuntu for scientists" section
 - ubuntu-devel will be used as a coordination mailing list, with [doc]
   in the subject
 - hornbeck started working in organizing together all the scattered
   parts of documentation already existing in the wiki, using /UDP as a
   starting page
 - development and sketches will be moved to
   /DocumentationTeam/Development

The meeting ended after 1 hour 45 minutes, with the intention of sending
the summary, the proposal and the other notes we have in -devel and
continue discussion there.

Ciao,

Enrico

P.S.
I welcome the people who were there to correct and complete possible
mistakes, omissions and misrepresentations.  I would also appreciate
feedback on making my IRC meeting reports better.
--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.ubuntu.com/archives/ubuntu-devel/attachments/20041015/1a4d8e9f/attachment.pgp