Summary by: Enrico Zini <enrico@enricozini.org>
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 already started:
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:
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
This IRC blurb:
< 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)
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.
There has been discussion about what format to use for the documentation we produce. We have talked about three different scenarios:
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.
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
Mantra #2:
"Cool thing! Let's put it into the TODO-list for the next-to-the-upcoming release!"
—Everyone, Warty Conference, Oxford
Mantra #3:
"First, get to do it. Then, document how to do it. Then, automate it."
—Custom Debian Distributions Meeting, Florence
Mantra #3:
"First, get to do it. Then, document how to do it. Then, automate it."
—Custom Debian Distributions Meeting, Florence
"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:
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.