RE: [xml] documentation wishlist (was:Bug or User Error)

[Ron Ohmer <rohmer aisconsulting net>]

When I get a free second...  I am going to dl the docs and see what I can do with them.  The problem I had over and over is:

Either A: I find the header for the function I want, but not the description.

B: I cant find either.

 

Now, it maybe that I am just used to looking in a specific way, and have not gotten the gist of how this website is put together.  I have spent many hours looking at it though.

 

In Daniel's defense though, it is rather insane to expect him to do everything.  So I will take on trying to make the docs a little more user friendly.

 

Maybe a discussion along the lines of what needs to be there would be in order.  Since, if I set them up the way I want them, that will surely leave others in the same boat I was in (Not being able to find stuff).

 

Ron

---

From: Phil Frost
Sent: Fri 1/30/2004 05:33
To: xml gnome org
Subject: Re: [xml] documentation wishlist (was:Bug or User Error)

Perhaps in the spirit of moving to solve problems rather than only
highlight them, I might suggest these two improvements to the docs that
would make them much more useful:

- add a search function, or an index. It is sometimes very hard to find
  the module in which the function in question is.

- get rid of the high contrast borders. The black borders, coupled with
  the link underlining, make it extremely hard to manually grep the
  docs. I'd say get rid of all the borders, or make them very faint. On
  my sites, I often use no border, but increase the cell spacing such
  that a pixel or two of the background comes though, and give the cells
  a very slightly different color.

Those two things would make the existing documentation many times more
useful, and reduce the frustration of those who do read the docs
greatly.

--
Phil Frost


On Fri, Jan 30, 2004 at 09:45:45AM +0100, Peter Jacobi wrote:
> Hi Daniel, All,
> 
> New year, new off-topic posting quota!
> 
> Thanks a lot for the great work, again, BTW!
> 
> Daniel wrote:
> >   Why bother building docs ? People simply don't bother to read them :-( it
> > is *extremely* frustrating :-(
> >   Why did you call xmlCleanupParser() for each document ????
> 
> On our commercial product, we started with a 200 page manual, covering 
> everything. Of course nobody read it.
> 
> We dumbed it down to 20 pages. Due to insufficent control of the external 
> translators, some silly stuff was in it. Nobody complained. We deduced, 
> nobody read it.
> 
> Now we have a one page "getting started" instruction sheet. 
> 
> (Of course online help also available but never used)
> 
> Optimistic people would assume, that software developers would have another 
> attitude towards reading docs. 
> 
> Daniel, most of those who read the online docs, don't show up with 
> redundant questions in the list, so it's only selective perception, which 
> lets you assume nobody reads yours docs. I hope.
> 
> Regards,
> Peter Jacobi
> 
> _______________________________________________
> xml mailing list, project page  http://xmlsoft.org/
> xml gnome org
> http://mail.gnome.org/mailman/listinfo/xml
_______________________________________________
xml mailing list, project page  http://xmlsoft.org/
xml gnome org
http://mail.gnome.org/mailman/listinfo/xml