Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Uriel <uriel99@gmail.com>]

> > The man pages have several flaws: there are too many;
>
> Again, I'm afraid I don't really understand this complaint. They are
> numerous, yes, because they're describing lots of different things.
> They don't make for the best introduction *on their own* for that
> reason, but they make an excellent reference - which is more or less
> their intent.

There is intro(2) is not a bad introduction either, althought it
certainly doesn't cover much.

Just thinking out loud here so I might make no sense, but I suspect
the issue is that the style of the plan9 documentation is very
different from what people have become used to expect, this days
people expects 'tutorials' and other handholding with many examples to
'copy paste' into their code and so on, which is quite different from
the Unix/Plan 9 documentation style of clear and concise information
and simple examples that help illustrate the general concepts, but
that does require the reader to actually *understand* things rather
than just follow an arbitrary set of steps.

Best wishes

uriel
>
> > some important stuff is hard to find;
>
> Sometimes, yes. lookman does a very good job, but is not perfect. Can
> you give examples of the types of difficulty you've been having?
>
> > "man page jumping" is a problem.
>
> Why? It's certainly easy enough to do - the acme integration via
> plumber is very nice. It's a "problem" in that it doesn't make for a
> nice, flowing introduction, but again, that's not their intent.
>
> My point about the man pages as regards an introductory document is
> mostly that it'd be bad to needlessly duplicate effort. I'd expect an
> introductory document to make extensive reference to the manual for
> the topics it covers.
>