doc howto: be a developer (Was: svn commit: r233994)

[David Crossley <cr...@apache.org>]

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.

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.

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.

-David

Re: doc howto: be a developer (Was: svn commit: r233994)

[David Crossley <cr...@apache.org>]

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.

-David

Re: doc howto: be a developer (Was: svn commit: r233994)

[Tim Williams <wi...@gmail.com>]

On 8/22/05, David Crossley <cr...@apache.org> 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.

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

> 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) and 2) it isn't really version specific
content, and 3) people wouldn't look for such a document in the
product documentation, they'd look for it in the project
documentation.

It looks great...
--tim