newbie-doc
On Mon, Sep 13, 1999 at 08:57:59PM -0400, Adam Di Carlo wrote:
> Jor-el <jorel@marvin.megadodo.umb> writes:
> > Aarrgh! Wrong address!
> > 2. Provide info on navigation (the OS), basic concepts, and common tasks.
> > Have information on how to find out about advanced tasks.
>
> Kinda like a Newbie User Guide ? I don't know if there are others
> competitors. You should work a little harded to identify exactly who
> you're intended audience is, and what their needs are. We are all
> pretty technical here, so generally, you should have a newbie you are
> working closely with when writing it (so they can read it and ask
> questions).
Just a reminder (sorta had a low profile lately) that I _am_ working
on a Newbie User Guide (tentatively called newbie-doc). This got a
lot of hashing out a while back and then simmered for a while as I
struggled with getting debiandoc-sgml functioning here at work
(non-debian).
Anyway, suggestions here (in the replied-to message) are not identical
to (but not in conflict with) what I had in mind. I was thinking of
exclusively writing documentation with the one exception that (per
_other_people's_ suggestion) the file (whatever it is) that gives you
a little message when you log in on the console would point you toward
the newbie-doc info. Naturally, the newbie-doc info would tell you
how to undo that:)
Anyway, A few primary goals for what I had in mind:
don't rewrite -- the linux world has lots of good documentation
the only problem with most of it is that it's one or more
of the following: too technical, "hidden", or too long
I would write 1-3 pages for a given topic (setting up ppp or sound,
etc) aimed at the best-case scenario and then give a voluminous list
of other resources.
Especially important, I would include a step-by-step "type this; type
this; ..." instruction with very little explanation. Not so much
encouraging that people shouldn't figure out what they are doing, but
it can be hard to figure things out if you have no broad outline of
what's going on.
#####################################################################
Anyway, I've just reached the point where I'm ready for a second round
of discussion and then I think it will be time to get writing. I
figured this is the place to do it.
Comments that I'm most interested in are:
1) Hey, Joe $^&)(*^% is already doing this... just help him
2) you should look at the LDP, DWWW, ETC, etc. :)
3) you get manpages from debiandoc-sgml by.... (unrelated :)
Thanks,
Michael
--
Michael Stenner Office Phone: 919-660-2513
Duke University, Dept. of Physics mstenner@phy.duke.edu
Box 90305, Durham N.C. 27708-0305
Reply to: