Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss

Good Documentation

118 views
Skip to first unread message

Jason Damisch

unread,
Aug 21, 2012, 4:07:20 PM8/21/12
to
Just for kicks and buckles, what percentage of documentation which you have seen is something you would actually call 'good'? 40% ? 20 ?

Jason

Richard Owlett

unread,
Aug 21, 2012, 4:14:34 PM8/21/12
to
Jason Damisch wrote:
> Just for kicks and buckles, what percentage of documentation which you have seen is something you would actually call 'good'? 40% ? 20 ?
>
> Jason

The documentation itself, or how it's read/interpreted.
I've just been told that my walker must weigh more than 1 TON.
P.S. I lift it with one hand ;/

Paul Rubin

unread,
Aug 21, 2012, 4:44:01 PM8/21/12
to
Jason Damisch <jasond...@yahoo.com> writes:
> Just for kicks and buckles, what percentage of documentation which you
> have seen is something you would actually call 'good'? 40% ? 20 ?

Most documentation I see is pretty good. That doesn't mean most
programs are well-documented. Programs are usually badly documented
because the documentation they should have is non-existent, not that
it's bad. You ask about documentation that I've seen, but that I can
see it at all means that it exists, which is a strong point in its
favor.

One issue bothers me about current (web-era) documentation practices
even when the docs are well-written and complete: the concept of
organizing the docs seems to have been abandoned. You get a bunch of
cross-linked web pages that if you spend enough time navigating,
eventually cover all the topics, but it's difficult to get everything
all at once.

In the past there was a tradition of putting all the relevant info about
a program into one big document called a "manual", which was designed so
you could get a solid understanding of the subject by reading through
the manual's pages in linear order starting from page 1 and continuing
til the end. Nobody seems to document that way any more.

Elizabeth D. Rather

unread,
Aug 21, 2012, 5:03:34 PM8/21/12
to
On 8/21/12 10:44 AM, Paul Rubin wrote:
...
>
> One issue bothers me about current (web-era) documentation practices
> even when the docs are well-written and complete: the concept of
> organizing the docs seems to have been abandoned. You get a bunch of
> cross-linked web pages that if you spend enough time navigating,
> eventually cover all the topics, but it's difficult to get everything
> all at once.
>
> In the past there was a tradition of putting all the relevant info about
> a program into one big document called a "manual", which was designed so
> you could get a solid understanding of the subject by reading through
> the manual's pages in linear order starting from page 1 and continuing
> til the end. Nobody seems to document that way any more.

FORTH, Inc. does. The SwiftForth Reference Manual, for example, is 246
pp. including 4 appendices and an index. But as a modern manual, it is
provided in pdf form with hot links, so that instead of *just* reading
it in linear order you can also go to any chapter from the ToC or index,
follow cross-reference links, search on keywords, etc., none of which
are supported by dead-tree manuals.

Cheers,
Elizabeth

--
==================================================
Elizabeth D. Rather (US & Canada) 800-55-FORTH
FORTH Inc. +1 310.999.6784
5959 West Century Blvd. Suite 700
Los Angeles, CA 90045
http://www.forth.com

"Forth-based products and Services for real-time
applications since 1973."
==================================================

Richard Owlett

unread,
Aug 21, 2012, 5:04:24 PM8/21/12
to
Are you implying the CPM-80 manual was readable? ??? ;/
YES, it had the _facts_ lol
I believe I've an early copy around somewhere ;/


The Beez

unread,
Aug 27, 2012, 6:06:47 AM8/27/12
to
On Tuesday, August 21, 2012 10:44:01 PM UTC+2, Paul Rubin wrote:
> In the past there was a tradition of putting all the relevant info about
> a program into one big document called a "manual", which was designed so
> you could get a solid understanding of the subject by reading through
> the manual's pages in linear order starting from page 1 and continuing
> til the end. Nobody seems to document that way any more.
It's really hard to do BOTH at the same time. The 4tH manual (530+ pages) has several chapters (modeled after the Unix manuals). The tutorial has been laid out in such a way that you can read and apply it, but also in a logical way so it build on the knowledge of previous sections. Like you'd expect froma tutorial.

Writing good documentation is hard and should not be underestimated.

Hans Bezemer

Mark Wills

unread,
Aug 27, 2012, 6:53:04 AM8/27/12
to
On Aug 27, 11:06 am, The Beez <the.beez.spe...@gmail.com> wrote:
>
> Writing good documentation is hard and should not be underestimated.
>

I agree.

And also, we have to recognise that some *users* are just plain-ass
lazy, and will not, under any circumstances RTFM, no matter how good
it is.

Those folk can't really be helped, and will move on soon anyway. If
they're not willing to invest real time in understanding the product,
and what it can do for them then they're just tyre-kickers, and will
move on.

The Beez

unread,
Aug 29, 2012, 5:12:18 AM8/29/12
to
On 27 Aug., 12:53, Mark Wills <markrobertwi...@yahoo.co.uk> wrote:
> And also, we have to recognise that some *users* are just plain-ass
> lazy, and will not, under any circumstances RTFM, no matter how good
> it is.
There is also the "documentation paradox" in that too much
documentation will make it harder to find the thing you're looking
for. Fortunately, in this time of electronic documents, it's easier to
access documents in different ways.

> Those folk can't really be helped, and will move on soon anyway. If
> they're not willing to invest real time in understanding the product,
> and what it can do for them then they're just tyre-kickers, and will
> move on.
Agreed. The only thing you can tell 'em is: "don't say it wasn't
documented!" ;-)

Hans Bezemer

Ed

unread,
Aug 30, 2012, 4:45:27 AM8/30/12
to
Richard Owlett wrote:
> ...
> Are you implying the CPM-80 manual was readable? ??? ;/
> YES, it had the _facts_ lol
> I believe I've an early copy around somewhere ;/

You didn't go out and buy one of the many books written about
CP/M ?

'Mastering CP/M' had a great reference section which described
and listed 8080 and Z80 instructions in alphabetic and numeric form.
More convenient than the official sources. I'm using it right now.



Richard Owlett

unread,
Aug 30, 2012, 6:47:54 AM8/30/12
to
That so many existed said something about usefulness, if not
quality, of the "documentation". I bought several on both
CPM and 8080/Z80.

gavino_himself

unread,
Aug 31, 2012, 3:33:39 AM8/31/12
to
On Tuesday, August 21, 2012 1:07:20 PM UTC-7, Jason Damisch wrote:
> Just for kicks and buckles, what percentage of documentation which you have seen is something you would actually call 'good'? 40% ? 20 ?
>
>
>
> Jason

1%

most docs really suck ass

tcl tutorial is honesly only one I could make heads nor tails of.

rest are out there and ignore basic things like files on unix

gavino_himself

unread,
Aug 31, 2012, 3:34:44 AM8/31/12
to
sounds like a cop out for not writing an intelligible manual

if your manual has 1 thing that doesnt work the reader goes what the fuck is going on here?

Ed

unread,
Aug 31, 2012, 4:09:01 AM8/31/12
to
I recall a Forth book purchased sight-unseen from FIG mail-order
that I regretted immediately upon receipt. There are authors (such
as Leo Scanlon) who can tackle a foreign subject and deliver a
usable book - and Forth aficionados who it were better had they
never put pen to paper :(



0 new messages