Re: newbie-doc

[Jor-el <jorel@marvin.megadodo.umb>]

On Tue, 14 Sep 1999, Michael Stenner wrote:

> 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 :)
> 

Michael,

	The thrust of my proposal doesnt have to do with writing a
document. Rather, it has to do with taking the existing documentation and
re-presenting it in a different way. So, I will not be competing with you
or any of the zillions of other people who are writing documentation.

	Bear in mind that in a CBT, most of the screen will consist of
graphical stuff, and the information content on a single screen will be
quite small. So the information cannot be a refence manual, or a FAQ, -
which is more suitably presented as a man page, or text document, best
read in an editor / browser. 


	The set of programs that I have in mind should be able to
accomodate some of the examples that you have in mind (for example,
setting up sound). But that wasnt what my initial intention was : the idea
wasnt to tell newbies how to setup things, but rather how to use things
after things have been setup already. This would be quite useful in
machines which come with Linux pre-installed, or for which the install was
done by someone other than the user.

Regards,
Jor-el