Re: Gnome 3 and Documentation

[Milo Casagrande <milo casagrande name>]

Hi Shaun,

Shaun McCance ha scritto:
> People do, in fact, read good documentation.  Well-written,
> task-oriented documentation can actually be an enjoyable
> learning experience.  What people won't read are interface
> descriptions.

I also feel that users tend not to read very long documents: read a 
little bit and then move away. At least I always preferred reading and 
writing task-oriented and concise documents.

But this is probably not true for technical people/users that need to be 
updated on new technology.

> If we're to change the way documentation is done, then we
> need to produce a new writing manual and a new style guide.
> These can safely slip by at most one stable release.  If
> we're exploring new user interface ideas, then we need an
> updated HIG.  I'd say this can slip by a release if we have
> a draft or development version available by Gnome 3.0.

GNOME is doing great here with HIG.

What I sometimes feel, is a lack in terminology consistency. I usually 
see this while translating, applications and/or documentation. It's not 
a huge problem, but sometimes it catches my eyes: small trivia 
differences in writing a word (pop-up popup, double click double-click 
just as an example) or use of different words for exposing the same 
concept/actions.

Now only the gdp-style-guide has a glossary, probably would be useful to 
extend this also to the HIG document with terminology that should and 
shouldn't be used.

> Most people have heard me talk about Mallard, the project
> I've had in the works for some time now.  Mallard is a
> documentation format designed to support task-oriented
> documentation.  Obviously, an XML format is no substitute
> for good planning and writing.  But the format can have
> a big impact on how we write and organize information.

What about FoieGras in this picture? I think that a good and (almost?) 
easy editor for writing documentation is needed. DocBook could be a 
little bit scaring at first...

I tried to use Conglomerate once for DocBook editing, but never been 
able to really use it. How is that project now?

> If we could get a a build team together to produce virtual
> machine images of vanilla upstream Gnome, it would be very
> helpful.  We need these sooner rather than later.  

What about this:

http://live.gnome.org/GnomeDeveloperKit

is it suitable or enough up-to-date for this task?

I knew they were creating virtual images for the development version 
throughout the development, but I don't know how vanilla it is/was, I 
usually use Ubuntu development version in this situation, even if it's 
not really vanilla.

I have never created a virtual machine so I'm asking it here: what would 
be necessary to accomplish that starting from GNOME svn/git?

Cheers.

--
Milo Casagrande <milo casagrande name>