GUADEC: longish account of things discussed

[Telsa Gwynne <hobbit aloss ukuu org uk>]

Okay, there were about three separate meetings I know of, and lots
of folks went out for a meal and drinks and they might have discussed
things there. I am simply going to summarise from my scribbles.

Ease of documenting things:

	o Martin Baulig made .debs of the GNOME extras to DocBook 
    for Debian users to be able to install them more easily. We
    need rpms as well. Dave or jrb (Jonathan Blandford) will do 
    that.

	o A task for Dave (or anyone who likes dsssl): we are trying
    to avoid gifs. The stylesheets still generate the odd gif for
    things like the little pictures next to things marked up as <note>.
    Those need fixing.

	o _Something_ has changed. There was very little activity for
    a while, and then lots of people got involved, and more importantly,
    lots of them stayed involved. We have a dreadful attrition rate,
    and Steve George spoke for everyone when he said we have to make
    it very easy for people to get set up to write DocBook. Whether it's
    just "lots of people on #docs" or (probably) the Handbook, something
    is helping to some extent, but we still lose people. (I know I've
    talked via email to a bunch of people who just fade out.) We need to 
    work out what helps and do more of it. The Handbook and the frequent 
    updates of it on the website are probably at least partly responsible 
    (IMHO, at least).

Licences:

	o We all seemed to like the Free Documentation Licence from
    GNU. Suggestion that we use it ourselves with strong hints in
    the handbook that others do too unless there's a really good
    reason we haven't thought of not to.
	- Sidenote to that, from my husband, who has been messing
    around with DocBook and some of GNOME's "generate docs from code
    comments" stuff: you can't use it for auto-generated stuff like
    he's been doing with the Linux kernel. This won't affect those
    of us writing user docs, but it might be relevant for people
    documenting code and APIs.

Timelines, milestones, goalposts:

	o GNOME 1.2. Regardless of how people end up announcing it,
    "GNOME 1.2" isn't a big GNOME upgrade: it's merely gnome-core,
    applets and utils. That's all. Basically, they're just waiting on
    our docs to release it. We decided that it's probably best just
    to throw everything we have currently at Jacob Berkman and George
    Lebl (maintainers) to get it in now. We can correct any whoopses in
    CVS, and they can get it released and out of the way. We set
    (and this is serious) a deadline of Friday 24th March (!) for 
    this lot, which are all that remain that we could think of:

	- the sawmill capplet for the configuration stuff
	- odd applets (some of which are very odd :))
	- the notorious gmenu
	- menu panel ("foobar panel") in the panel docs.
	- possibly session management. 
    We decided to ignore gmenu out of existence. Sasha (or Dan? 
    Someone, anyway) did a great job at summarising it in the panel
    docs and it causes huge headaches. (Anyone who wants to _try_ is
    welcome, of course, but it's really horrible to write about.)

    Basically, George and Jacob want to release, they want to release
    soon, and that's a horrible deadline but since they have to link
    in all the help and whatnot after we've written stuff, that still
    means it's later than they'd like and with fewer docs in than we'd
    like. Call it a compromise :) 

	o I'll throw a brief thing about the applets in here: Jacob
    is still deeply unkeen on a floating "docs"/"help" subdirectory in the
    top of gnome-applets, and that's something that would be required
    to generate the pretty "all ready for printing" gnome-applets doc
    or one big set of interlinking HTML docs. (He has a list of technical 
    objections rather than a "I don't like it" approach, I should point out.) 
    I am going to try playing with scripts, and seeing whether there's a way 
    around those problems.

	o After the 1.2 stuff, there are two big GNOME releases to
    know about. (This is mostly from one of the lectures.) One
    scheduled for August is the big desktop upgrade: the latest
    funkiest stable version of user tools, the inclusion of the 
    nautilus file manager (which is particularly relevant because it
    will replace the help browser), the inclusion of the Evolution
    stuff (Aaron's problem :)) and so on. That's our next big target. 
    The next one after that, scheduled for November, should in theory see 
    few apparent changes to the end user stuff: the big changes are that 
    the core libraries will be massively updated and all the programs will 
    have to be ported to run on them. I _think_ this means there won't 
    necessarily be huge amounts of user-apparent stuff. But for anyone 
    involved in documenting code or APIs etc, this is definitely one to 
    know about.

    There was a strong "or thereabouts" flavour to those month names.
    Since GNOME has been accused of rushing out before ready before,
    I had the feeling that people would rather delay a month and have
    it solid than release just to make that month and get slammed.
    Seems reasonable to me. But of all those, the important one will
    be August for us, and that leads us to nautilus, which will replace
    the help-browser.

Nautilus and why it's important.

	o This could almost be a separate post. Nautilus is a shell
    (hence "nautilus", ho ho) which will contain various things. Everyone
    has heard about the file manager. Another part will be the help
    browser. In appearance it's similar to GMC (and every other graphical
    file manager) and Mozilla and so on: toolbar at the top, two panes
    beneath. Right hand pane has (for filemanager) icons of files or
    (for help stuff) contents of help. Left hand pane has various
    possibilities. The Eazel folks are not wedded at all to the idea of
    a tree view on the left: they think it's not necessarily intuitive
    or useful for many people or situations. So they have various ideas
    of things you could have in the left-hand pane for the filemanager,
    and Jon Blandford said that if we have good ideas of what should be
    on the left for the help browser, now is a _very_ good time to voice
    them. (As an example, I am not keen on a tree structure, but a
    "other documents which deal with this topic" list (based on index
    or id tags) on the left sounds cool to me: other people note that
    lots of Windows and Mac users are very used to tree structures.)

    As I understand it, you would be able to choose which of these
    views on the left you get, so it's not a vote. It's also up to the
    developers which suggestions they incorporate. Eazel are apparently
    going to be setting up a user test lab (where you video people
    using stuff) so they may well have some important things to add
    to this. It would probably be good if one of the Eazel (or other
    nautilus hackers, but most of them are apparently at Eazel :)) 
    folks is on this list or if we have someone there we can ask 
    stuff of, because they have lots of ideas and usability concerns
    and we should probably listen to them when they say something :) 

	o The other big thing related to this is that nautilus will be
    generating html on the fly from docbook files. Very very fast. Jon
    has been doing a prototype tool for this. So far it handles only
    some of the DocBook tags, and he wants files to throw at it. I have
    the vague idea that it only does XML but I may be very wrong there. 
    (I assume this is related to the whole "when you click on something,
    you should get what you expect" aethos the Eazel guys have, which
    resulted in a demo of MP3 directories with icons of the album
    covers in question; clicking on the album covers gave you a track
    listing; clicking on the track started up an mp3 player; etc.)
    And how the resulting documents get put together, and how nautilus 
    searches them and so on will be based a lot (much more than I, for 
    one, realised) on the contents of the documentation. That leads on to...

Doc structure for Nautilus.

	o We have can lots of little files, but we're going to
    have to do sensible indexing between them. Apparently good indexing 
    is such a specialised task that some people are employed just to do 
    that. It's possible that some of the people listed as having lots of
    professional experience in tech writing on the Open Source Writers'
    Group volunteers list can help us here. If so, that would be really
    handy.
    
	o There are two ways of reading help and documentation which
    conflict slightly: there's "find me more about this particular
    problem and how to fix it now"; and there's "tell me more about
    this subject in general". I don't think we got beyond "this division
    exists", but it's a useful thing to remember because it will affect
    how we mark things up and write them and so on.

	o I haven't mentioned XML in all this. XML will be a good thing
    in many ways. We can define our own tags should the need arise.
    GNOME has an XML parser written by Daniel Veillard, who knows a 
    _lot_ about the subject. He says it's "almost" entirely standards-
    compliant: I have been told by others that it's one of the best
    around and that his "almost" is a bit misleading. There are downsides,
    of course: either someone sits there and changes all the DTDs by
    hand, or spends a similar amount of time writing a script for it.
    And most importantly, the DocBook XML DTD is currently beta. Dave
    strongly suggested we don't start switching until the DocBook XML
    stuff is finalised. We all thought that sounded good. But it's still
    well off on the horizon. 

	o As well as indexing, the issue of the glossary came up 
    again. With caveats, there was some support for this. I must admit 
    to bias: I think it would be super-cool if things that are marked
    as <glossterm> and are being mentioned in the right hand pane
    had the glossary definitions in the left-hand pane. Dan Muet raised
    the problem of consistency: if there was a glossary being written
    as a separate document, then constantly having to check that all
    the time would rapidly become a pain. Also, what happens if you
    have a word like "root" in there, which might be "root directory"
    for one doc, "root as UID 0" in another, and the "root window" in
    another? Nautilus would need a way of knowing which to refer to.
    But if everyone chucks their own definitions in, it will be
    inconsistent and people will want to change things to their ideas
    of what something is and how best to describe it in one sentence :)
    Dan B (Daniel Barlow, LDP and OSWG contributor) pointed out that
    you can also end up with words on every other line highlighted if
    you get too carried away with this, and constantly to-and-fro'ing
    between doc and glossary is disorienting.

	o Context-sensitive help will finally become a reality with
    nautilus, too. The idea is that each button on an app would have
    a reference number associated with it in the code. Then someone 
    writes the help that's specifically for that button at that stage 
    (some have different effects or will only work at one particular 
    stage: you can't 'undo' if you haven't done anything yet, etc), and 
    that gets attached to that number (somehow. I gather this is a
    code problem, not a doc problem). It sounds rather like the way 
    translation files are done, actually. 

    Caveat: I remember discussion on context-sensitive help but I now
    can't remember whether it was going to arrive because of nautilus
    or merely at the same time as it (the August GNOME stuff). 

Tools and dates:

	o As I said, there's projected GNOME release dates. (core/
    applets/utils "imminently"; desktop improvements August, lib 
    changes in November). There are also things we expect to come out 
    at some stage in the docs arena. These dates are possibly a little 
    firmer than the GNOME ones, but not much:

    Currently we have DocBook 3.1+png thing.
    Next will be DocBook 4.0 which includes png support. May 2000. Ish.
    Then DocBook 5.0 which will have the official XML stuff. (Much
    later, like around the end of the year, perhaps.)

    DocBook XML betas will be around before that, but we don't want to
    redo things because beta->official broke assumptions we made or
    something, so we'll avoid the betas. 

Future:

	o I think it's all above: some people have things they 
    volunteered to do (eg rpms). The things for gnome core/applets/utils
    to be done asap just to get the packages out. Things for August
    to be what we aim at as a priority. 

	o One thing that arose was that a lot of Dave's Red Hat time
    has been spent doing GNOME documentation and related things, but 
    he can't guarantee it will stay that way, so it would be sensible 
    to have someone ready to take over maintaining etc just in case RH 
    decide he should be doing something else instead. Dave's suggestion
    was that it needs to be someone who's not doing it part-time, as 
    there's lots of stuff like answering email that mounts up, and 
    promptly nominated Aaron, as a about-to-be-full-time documenter :)

	o It wasn't explicitly said, but I think "keep the handbook
    and webpages up to date" is fair to put in here: they seem to have
    had quite an effect. But that may be editorialising on my part.
   
Overall:

	I'm sorry this was so long. I've tried to stick to what was
    said and include all points of view, although I have omitted lots
    of "how Apple and Windows do help" and discussion about "Well, 
    could nautilus do <xxxx>?". It was cool to see how many of us there
    were who actually made it, especially given that we were by no means
    all of the GDP. I believe we may be well into double figures. Ooh :)
    And I met several people who were asking about documentation or who
    had been doing some for their programs. (Is it me, or is half the free 
    software world suddenly discovering DocBook?) I have not included 
    details of Dave's talk: but that was cool and he's putting the
    slides in CVS or on the web or something, and they had all the main
    points. And it was _hugely_ well-attended, which was definitely cool.

	Things we didn't discuss (unless it happened at the meal or
    pub?): consistency, any need for an overall editor, capitalisation
    of 'panel' etc, and the bloody mouse button naming thing :) We also
    didn't talk a lot about the use of entities. And we forgot all about
    the templates, too. 

I _think_ that's it. Corrections welcome, comments welcome, changes in
emphasis welcome. Might be best to reply in several different parts, I 
suppose, since this covered a lot of ground. 

Now I'm off to catch up on gnome-doc-list.

Telsa