Re: Documentation change requests

Re: Documentation change requests

[Štěpán Němec]

Peter Stephenson <p.w.stephenson@ntlworld.com> writes:

> We often get comments about the documentation being substandard.

Interesting. I don't remember seeing any such comments. In any case, let
me say that I consider Zsh documentation definitely superstandard[1]. ;-)

Of course, anything can be improved, so thank you (and all the others
involved) both for the existing docs and your ongoing pursuit of
improvement.

  Štěpán

[1] In terms both absolute and relative compared to other shells and
software in general.

Re: Documentation change requests

[Peter Stephenson]

On Thu, 6 Jan 2011 11:00:50 +0100
Štěpán Němec <stepnem@gmail.com> wrote:
> Peter Stephenson <p.w.stephenson@ntlworld.com> writes:
> 
> > We often get comments about the documentation being substandard.
> 
> Interesting. I don't remember seeing any such comments. In any case,
> let me say that I consider Zsh documentation definitely
> superstandard[1]. ;-)

As is probably already clear from the examples I gave, I really meant
'inaccurate' (which is the particular concern) or 'needing improvement'.

However, I think we do sometimes get comments where someone has been
confused by the documentation and says so.  The trouble is it's usually
not possible to work out from someone's confusion what to do to improve
the docs.  That's why I'm really keen on getting suggestions afterwards
that say explicitly I got confused *here* and I could have done with a
better pointer *here*.  If someone was confused and has been put in the
right direction by the list, this should be useful for future readers.

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom

Documentation change requests

[Peter Stephenson]

We often get comments about the documentation being substandard.  In
future, it would help me a great deal if people concerned enough to want
the manual changed could do as much work themselves as possible.

Please could you edit the appropriate Yodl file from the zsh
distribution and send zsh-workers@zsh.org a 'diff -u' ('diff -c' will
do) of any changed files.  If you don't have the latest CVS/git source
the last distributed versions is usually fine, the documentation doesn't
change that fast and even just looking at the diff helps me find what
you're talking about.

The files are in the subdirectory Doc/Zsh.  They're basically plain text
and I don't expect you to know anything about Yodl.

- You don't need to do any formatting at all, just add some clearly
marked text.

- You don't need to make any attempt at definitive text and I don't care
how bad your English is.  I'm perfectly happy with comments pointing out
the problem, e.g.

!!!Shouldn't the manual point out this doesn't work with blah blah blah?!!!

!!!For option -X it says blah blah, shouldn't it say the same here?!!!

!!!I was expecting something about feature blah here, it was hard to
find in its current location [please also mark that location with
some text, anything will do, so I can compare]!!!

!!!It doesn't really do 'blah', it actually does 'blech', so the wording
needs improving!!!

etc. etc.  (Of course, if you *do* think you know what it should say
please send that instead.  To emphasise: actual diffs really do save a
lot of time over descriptions of what needs changing.)

It would help even more if you do this in all the relevant locations
that you're aware of (e.g. for multiple features with similar effects)
so I don't have to spend time hunting for things you already know
about.

This will save me considerable time since I won't have to go through the
documentation trying to second guess where and what you're complaining
about and in what way you think it could be improved.  If you go through
the exercise yourself, I think you'll see how much quicker it is if all
I need to do is make an edit to something you've submitted rather than
start hunting through files from scratch.  I really do need all the help
I can get.

(I may repost this occasionally since I don't think there's another
really good way of drawing list users' attention to it.)

Thanks for your help.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/