Re: (Was The GNOME Handbook of Writing Software Documentation)

[lacage email enst fr (Mathieu Lacage)]

David Mason <dcm@redhat.com> writes:

> Now something else
> 
> 
> <rant>
> 
> But that has been my whole point to anyone who will listen -
> <important part>Graphical SGML Editors of this Nature(Conglomerate)
> make it too easy to minimize your markup!!!!!</important part>. It

What do you mean ?

I don't understand this. I am sorry: GUI, especially the one which seems 
to be chosen by conglomerate (never tried it : just seen screenshots)
is not obliged to allow you only to write and not structure. 
Such an application seems okay as it allows easy markup and visual
feedback of the markup.

However, you mentioned you tested it which I have not and you seem to say
that it is not the case. Please, could you let us know why: if it is so,
then the app needs to be improved.

> happen with every app that has taken this approach - it is way to easy
> to miss something like <guilabel> when all you have to do is write -
> not tag and write!
> 
> I know people keep saying Conglomerate is the end all to our
> documentation woes - but it is not! From my tests of it - it does
> things a bit oddly (a stylesheet for a DTD to use *in* the editor
> only???) and it can make for badly marked up docs - have you seen the
> raw output?

well, I am sorry but I feel I miss your point.

If you say that conglomerate output is bad, I take your word for it:
conglomerate is simply bad and this has to be corrected.

What I say is that :
1) we will need to switch to XML for our docs.
2) switching to XML has nothing to do with using GUI app to write docs.
3) GUI apps like conglomerate are expected to lower the level of knowledge
users need to write doc. -> This is good. pause. This is good.

I am myself not likely to write any doc using such a GUI because
I like the Xemcs indentation of SGML/XML.

> 
> Thats why I was so disappointed to hear that the only thing even
> remotely related to docs at GUADEC was going to come from the GUADEC

Yes, I am sorry for this and I regret it myself but the reasons for this
are NOT because "we are trying to build doc apps".

> people - we aren't trying to build doc apps - we are trying to get
> people off their rear ends and write the docs that are so desperately
> needed if GNOME is ever going to be taken seriously!
> 
> </end rant>


Mathieu