forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: doc howto: be a developer (Was: svn commit: r233994)
Date Mon, 22 Aug 2005 12:22:31 GMT
Tim Williams wrote:
> David Crossley wrote:
> > Tim Williams wrote:
> > > This is essentially what I was hoping the Developers Guide would
> > > eventually be.
> > 
> > Tim refers to site-author/content/xdocs/developer-guide.xml
> > 
> > We talked a while ago about providing such documentation
> > and today we both added our partially finished work.
> Sorry, I should have communicated better, when I changed laptops a
> while back my original doc got blasted and I had to recreate what I
> could remember.

Oh that is a shame. We need to get any work on
docs committed ASAP, even if it is half-finished.
Fixme notes are okay in published documents.

By the way, my comment was no criticism.

> > So now there is docs_0_80/howto/howto-dev.html
> > 
> > > I'm in favor of just removing the developers guide.
> > > This is good stuff.
> > 
> > We can merge the content. It seems to complement the howto.
> I'll remove mine as it's duplicative.

I have kept a copy so that i can reuse some of its text.

> > Are people happy with the Howto format for this document?
> > 
> > The document will eventually grow too big, so some of the
> > topics should be split off into their own document.
> > 
> > We should also revise the contrib.html document. It was
> > borrowed from Cocoon and some sections removed to get it
> > published quickly. It could refer to these howto docs.
> I like the content, but I think it should get promoted out of a how-to
> and somewhere on the main site.  This is for a couple reasons: 1) it's
> not really a how-to in a typical sense (i.e. step-by-step instructions
> towards a specific end-state)

The more complex topics will eventually get
split out into separate documents. Some would be
step-by-step docs.

Sure, this high-level one could be a normal doc,
but list the intended audience, purpose, pre-requisites,
etc as sections.

> and 2) it isn't really version specific content,

Some of it could easily be version-specific.
However in general, i agree. We could probably denote
any variations.

> and 3) people wouldn't look for such a document in the
> product documentation, they'd look for it in the project
> documentation.

We can have howto documents at the top-level.

> It looks great...

Thanks. It is good to just get some the tips written
down somewhere.


View raw message