Re: summarizing docs-on-the-web discussion

[John Fleck <jfleck inkstain net>]

On Tue, 2002-10-22 at 21:45, Jeff Waugh wrote:
> <quote who="John Fleck"/>
> 
> > The forms:
> > 
> >     Chunked, displayed HTML
> >     downloadable PDF
> >     gzipped tarball of HTML (both chunked and single-page)
> >     Devhelp-compatible forms for the API docs (?)
> 
> [ I don't grok devhelp enough to know if the docs can be easily generated in
> an automagic fashion. It's essentially HTML, so I wouldn't be surprised.
> I'll ask Hallski and Co. :-) ]

Devhelp is not essential, but would be nice assuming the creation of
Devhelp books from API doc source is easily scriptable/automatable.

> 
> > The magic:
> > 
> >     Each doc will get its own directory on the web site. Quoting Jeff:
> >     "You tell a given directory that its content comes from a
> >     particular CVS server, module, branch/tag, which file is the root
> >     document etc. The docs are pulled in and built as if they were
> >     part of the tree already."
> 
> Yeah, separate directories would be greatly appreciated. :-)
> 
> > What we still need to do:
> > 
> >      Come up with a list for Jeff of all the cvs docs (with branches)
> >      so he and Steve can start waving their magic wands.
> > 
> >      Come up with a list of additional docs that are needed.
> > 
> > Does this about cover it?
> 
> Pretty much, I'd just add some stuff about how to deal with documentation
> that is under development. In some cases (for software docs especially),
> that's a simple matter of branches, but for things like the User's Guide,
> Porting Guide and other developer guide docs, how will we handle it?
> 
> It would also be good to have a fairly strong plan for the docs information
> architecture to come from you guys. I think that only a few special docs
> will sit outside each major documentation section...
> 
> Can't even think of any off the top of my head - Oh! Yes I can, the release
> notes would not be there, they'd be in the release area, under start/.
> 
> So, other than examples like these, you can pretty much rely on having your
> own playpen within each big area ("Users", "Developers", etc.)
> 
        
Jargon alert! Jargon alert! When you say "information architecture", what that
means is that we need to come up with a plan for the directory structure and how
the navigation would work within that directory structure - what sort of
index page there would be for each of the main branches of the tree,
etc., right?

And we probably also need to settle out what stylesheet(s) we want to
use for the generated html, too, eh?

Cheers,
John
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com

"Sometimes, a diner is all about the mac and cheese." 
  - Zippy the Pinhead