Re: documentation for novice and newbies
On Tue, Feb 06, 2007 at 06:43:08PM -0500, Roberto C. Sanchez wrote:
> On Tue, Feb 06, 2007 at 06:19:00PM -0500, Michael Pobega wrote:
> >
> > Sounds like exactly what I had in mind, and seems like a pretty good
> > battle plan for jumping into the documentation. What format will the
> > document be written in initially, plain text? I figure if we do plain
> > text initially (with a .html extension for word wrapping) we could
> > easily mold that into any other format.
> >
> I hate to use buzzwords, but this might fit with well with something
> like XML (or probably SGML), since it is easy to create transforms into
> different formats. The same source can be used to generate plain text,
> HTML, PDF and so on.
>
> You might want to check how the current Debian documentation is done. I
> know that they maintain it in some sort of CVS or Subversion repo which
> is accessible online. There are also packages in Debian to ease this
> sort of thing.
>
I just checked out wiki.d.o. There is an old newbie that doesn't seem
to be maintained (last was last changed 2004-95-04). If we want to use
wiki.d.o, we need a title page. We could use newbie, cleaning out
the old links or we could come up with a new name. Something like
Debian for newbies and novices, a.k.a. wiki.debian.org/novice
If we go with the wiki, then that fixes the file format. If we go with
another format, we need a host for that to then point to with the wiki.
Unless someone knows how, I'm going to go ahead and play with wget on a
wiki page that has sub-pages (as opposed to external links) is such
exists. Actually, I have to see if the wiki has sub-pages or if its a
flat set of pages that can reference each other. Either way, if I can
use wget to pull a wiki page off the wiki then that gives us html. If I
can then turn that into ps and pdf easily, then that problem is solved.
Note that my primary browser for the wiki is lynx, so that also gives us
plain text. As much as possible (and perhaps there's no other way with
the wiki), we should avoid graphics except as non-critical eye-candy.
I.e. don't give an example as a screen-shot.
Note that there's a from-windows-to-debian page already. Maybe what we
need to do is adopt a few of these older pages, each of us picking pages
that we know something about, with perhaps the
debian-for-newbies-and-novices page linking to each of these adopted
pages.
Doug.
Reply to: