Re: summarizing docs-on-the-web discussion

[Amy Kahn <amy zoned net>]

hey...I was the information architect on this, but someone told me that 
the IA was already established and they didn't need my services. If anyone 
needs directory structure work, I'm a professional IA.

Willing to help. Direct me to the problem.

On 23 Oct 2002, John Fleck wrote:

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

-- 
Amy Kahn

home: (617) 879-0064	1572 Beacon St, Apt 2
cell: (646) 234-8109	Brookline, MA 02446

Math problems? Call 1-800-[(10x)(13i)^2]-[sin(xy)/2.362x].