Re: Suggestion for Newbie Guide Lines (ITP)
On Thu, Jul 22, 1999 at 08:24:06PM +0200, Colin Marquardt wrote:
> * Michael Stenner <mstenner@phy.duke.edu> writes:
>
> > a) using html (this would help us -- we'd just mirror each other)
>
> We still need an ASCII document that tells newbies about lynx or
> Netscape in that case, IMO.
Agreed.
>
> > b) having a table of contents and index ( <- index might be hard )
> --------------------------------------------^^^^^^^^^^^^^^^^^^^^^^
>
> Not too much if the base is SGML or (La)TeX.
That makes me happy. It will probably be in debiandoc-sgml by Martin
Bialasinski's suggestion. I'll have to look into this, though.
> > c) trying to keep the documentation very short (ideally a page or
> > less) and step by step, with links to more complete info.
>
> This "very short documenation" should be in plain ASCII, IMO. It
> should include links, of course, whereever they may lead.
What do you mean by ASCII links? You just mean references? I don't
mind providing and ASCII version, but I think that for ease of
navigation, well designed HTML (as a final version) would be best.
Although I can think of a few scenarios that might make us both happy:
HTML "paths" that all end in ascii docs, for example.
> I also think that the bigger newbie documentation you seem to have in
> mind (judging from the TOC and index reference) is already written,
> manyfold. We just need a "jump-station" to the best of them, put in a
> prominent place (/etc/motd was my suggestion for a jump-station to
> the jump-station).
That's precisely what I had in mind. For example, On compiling in
sound support, I would list the things they need to type and click
with only modest fill. I would refer to the mountains of
documentation if they want more detail. I see this project as more
"organizing documentation" than "writing documentation".
On Fri, Jul 23, 1999 at 10:53:04AM +0200, Joachim Trinkwitz wrote:
> What about using/modifying/enhancing dwww -- I think it would be good
> to take an existing application as starting point instead of adding
> another one to those already there (dhelp is there to, but doesn't
> work for me).
Great. At this point, what I am most interested in is finding what
documentation and documentation frameworks already exist. In fact, I
think I'd like to work on that exclusively for now. I will certainly
make note of topics that should be included, but in the present, I
will focus on _centralizing_ the documentation in the "best" way.
If anyone else wants to tell me about
1) sources of documentation (LDP, /usr/doc/HOWTO/, etc)
2) documentation frameworks (dhelp, dwww, info, etc)
both would be very welcome. There's so much good stuff out there that
I'm sure even "not-so-new"bies like myself don't know about all of
them.
-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: