[Zope3-dev] documentation project at z3 sprint?

[holger krekel]

Jim Fulton wrote:
> holger krekel wrote:
> > Jim Fulton wrote:
> > 
> >>kapil thangavelu wrote:
> >>
> >>>is there interest in such a project? with an alpha by the end of the year, 
> >>>having some more narrative docs (as opposed to interfaces and unit tests), 
> >>>would be a good thing. its not as sexy as coding, but its part of the 
> >>>building the platform. 
> >>>
> >>I agree that more narrative docs are needed. I'll note that a number of
> >>the responses you got were for tools to generate interface docs. :)
> >>
> > 
> > And you disagree that they are needed and would be very helpful?
> 
> Given that we have lots of interfaces, automatic docs
> provide relatively little value.

Sorry, i don't understand the reasoning behind this.  Maybe
you misunderstood me.  Of course with autogenerated docs
comes a search-interface and graphical views (sooner or later). 

I think browsing (especially with web-browsers) is especially useful 
if you have lots of information but don't know how to find it.

And browsers can provide a graphical view that textual 'grep' 
techniques can't.  Although i prefer cmdline interfaces often
over graphical ones, it doesn't diminish the use of a
search interface (think google) if you need to lots of infos.
And you want Zope3 to have lots of development infos, don't you?

> It would be nice to have a document that
> listed and catagorized all the interfaces, but I don't think such a thing
> would be automatically generated.

maybe true. 

    holger