complain about the bits that have genuine problems. So far you have
mostly complained
With all due respect, Steve, information organization IS a genuine
problem.
And part of that is not due to any fault with the manual, but its
proximity
to the rather confusing web pages. I don't know if it's my browser(s)
or not, but the pages describing the jtag tools have huge duplicated
sections
in the middle, which is extremely disorienting.
The tools page would make a lot more sense with a tiny table of contents
at the top with a 1-liner describing each, and a link down to the
relevant
subsection. Maybe it should be subsumed into the manual?
Indeed, Chapter 10 of the manual is a good start. In fact, the section
on CVS is fantastic.
Why is it at the bottom, when "Installing mspgcc" is Chapter 2?
But if you come across the similar instructions in the "regular" (i.e.
not manual)
web pages, if you can find them, it's a bit of a mess.
I think (my opinion only) that the Shopping List section would benefit
greatly from a bulleted format, where each item is named and linked
right at the front, with the discussion following, rather than having
to muddle
through the words and multiple links to figure out what you're after.
It's
also MUCH easier for reference and maintenance (IMNSHO).
As Steve points out, most of the info is already there.
It's easy to underestimate the effect that minor reformatting can
have on useability for readers who don't already know what they're
looking for/at. Documentation structure is at certainly as difficult to
implement as code structure, and as important. Much easier to
debug, tho.
I think a great improvement of the entire site could be achieved by
removing or severely editing most of the web pages that inaccurately
or unclearly duplicate information in the official manual.
Not only will there be fewer distracting RTFM discussions for the
developers,
but keeping all the information current will be much easier.
A downloads page - either on the regular site or a pointer to the
manual - would
be a vast improvement, along with removal of the the in-text code links.
Sourceforge's download's page is pretty good, in some respects, but
obviously
only covers components hosted locally, and then doesn't provide much
context while you're shopping.
'Course hacking docs is pretty boring when you've got code calling...
I'm sorry to be the squeaky wheel on this issue, but I've both
created and suffered confusing docs many times in the past.
Again, I think everyone had done great work on this massive project.
Thanks,
-Ethan
On Feb 26, 2004, at 10:39 AM, Steve Underwood wrote:
Hi Ethan,
Your last message of things that need adding to the build instructions
actually reads like the contents page of section 10 of the manual.
Some sections of the manual are a little muddled. I've reworked some
stuff a couple of times to try to improve that, and certainly some
things could still be better organised. However, the build
instructions are pretty clear, and are only split between two pages in
the HTML built from the docbook. One is the shopping list, and the
other describes what to do with all the pieces. I hardly think that
represents docbook terribly fragmenting things. If two pages drives
you nuts, I don't think there is a lot we can do to help. :-) The only
part of the shopping list section which is not in a nice list is the
basic GNU packages. I'll change that, as it would be clearer. Checking
out the stuff from mspgcc at Sourceforge is shown as actual commands,
and the tools you need to have installed is already a bullet pointed
list.
Any reports of errors, omissions and out of date items are gratefully
received. However, try to complain about the bits that have genuine
problems. So far you have mostly complained that it should look like
it already does. :-)
Regards,
Steve
