[doc] Documentation meeting summary
enrico at enricozini.org
Fri Oct 15 14:46:52 CDT 2004
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):
Mentioned but not present: JohnLevin, BenEdwards, KevinWixted
After a short presentation, we collected some links on work that has
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
- 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
- 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
4) Establish channels and formats for dissemination of the
- 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
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
< 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
- 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)
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
There has been discussion about what format to use for the
documentation we produce. We have talked about three different
- 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
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.
Enrico posted three mantras that produced enlightenment in one of the
"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)
"Cool thing! Let's put it into the TODO-list for the
(Everyone, Warty Conference, Oxford)
(or else, the upcoming release we're working on right now will
"First, get to do it. Then, document how to do it. Then,
(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.
- Enrico will post the proposal draft he's been working on up for
- Enrico will post the list of possible documents we could start
- 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
- development and sketches will be moved to
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.
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
Size: 189 bytes
Desc: Digital signature
Url : http://lists.ubuntu.com/archives/ubuntu-devel/attachments/20041015/1a4d8e9f/attachment.pgp
More information about the ubuntu-devel