Re: summarizing docs-on-the-web discussion

[Jeff Waugh <jdub perkypants org>]

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

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

I'll post other things as I think of them. :-)

Thanks John, good to get these plans written down,

- Jeff

-- 
             It's not just a song! It's a document of my life!