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

["David C. Mason" <dcm redhat com>]

lacage@email.enst.fr (Mathieu Lacage) writes:


> 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.

When you are in the process of writing an sgml/xml doc in (for
example) Emacs and you come across a word that needs to contain markup
- you add the markup. Its all part of the process of your writing. If
you use a GUI to do the document and you come across the word - you
have to stop typing - grab the mouse - go through some menus - find
the tag you want - and 'register' the word with the markup. Most
people end up typing the whole thing and then going back to the
beginning and searching for words that need markup.

It (and the prime example would be people who use Adept's popular SGML
GUI) tends to make people miss a lot of markup that they would
normally have gotten if they had just written the SGML/XML to begin
with.


> 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.

Well your last line will answer one question - I like the indentation
as well, but the output from Conglomerate does not indent - does not
add returns - in fact, it has NO SPACES between words, phases,
sentences, or paragraphs. It is a continuous stream of words that is
incomprehensible when someone like you or I use Emacs to work on the
doc.

I agree we will need to switch to XML at some point - but I'm not sure
we should do so until OASIS makes and official DocBook XML DTD -
otherwise we could be using a buggy DTD. - The difference between the
two so far is just the heading anyway - so it is likely we can process
our SGML with and XML parser if we tell the parser to ignore the
headers. What I'm really saying is - moving to XML will be the easiest
thing we have to accomplish.

I agree that a GUI doc app may help new people come aboard and start
writing - and that is good, but if we get output like Conglomerate -
those of us who will need to do things with those docs - like edit and
change them, will be very frustrated.

As I have said before, we can start getting new writers now by simply
telling people that it is ok to submit their docs in ascii and those
of us who know DocBook will mark it up for them - once they see their
own docs returned in markup - they will start to learn and we will
have more volunteers.


> 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".


I am not trying to blame you here - you have done a wonderful job in
organizing the event - I am just worried that those who work hard
everyday getting GNOME done do not realize that their masterpiece will
lack such a fundamental feature as docs. They are working very hard to
get to another release but their plans *never* include the time (and
people) it will take to write the docs for all of these features.

It is partly their fault, it is partly my fault, and it is a very big
downside to the open source community in large.

Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com