cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <stev...@outerthought.org>
Subject [rant] Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Date Mon, 24 Mar 2003 14:15:05 GMT
On 24/03/2003 14:23 Stefano Mazzocchi wrote:

> I don't expect 2.0 to live long after 2.1 is out. There is no reason to.

To be really honest, I'd like to see some facts backing this statement. 
Not technical facts, but truly compelling reasons to make the switch. If 
people don't go with the flow, or with xmlform, why should there be a 
reason to switch?

> If there is something back-incompatible, it's a bug and it will be 
> fixed. Nobody should have problems in switching to 2.1 and if they did, 
> we fix their problems because we (and them) *expect* an easy migration.
> 
> At that point, there will be only *one* repository for docs and it will 
> live close to the code it belongs to.

Sigh. I don't understand, and perhaps will never understand, what this 
obsession is with keeping docs close to code.

I see three types of documentation involved in a generic software project:

  * code-based documentation, aka Javadocs & comments
  * reference documentation, which could possibly be partly generated 
out of the above, and states the exact input/output requirements and 
behavior of components
  * 'user' documentation, like 'building new Cocoon components', or 
'installing Cocoon on Znorbaf appserver'

I agree blocks & modular builds kinda spoil my picture, but the reason 
why I think all of these are wildly different, has to do with flow and 
access trails. Ultimately, one might think docs will be generated using 
some Javadoc++ process, as some novel language features in c# and Java, 
and tools like xdoclet are trying to suggest. I'm still one of these 
firm (silly?) believers that good user documentation is created with a 
blank editor screen in front of you, and that a decently written 
document of several screens long might be more helpful than the 
technically correct, hyperlinked-to-the-max, autogenerated alternative. 
For some examples, please see:

- http://xml.apache.org/forrest/your-project.html
- http://xml.apache.org/forrest/linking.html
- http://wiki.cocoondev.org/Wiki.jsp?page=DevelopingComponents
- http://httpd.apache.org/docs-2.0/mod/mod_include.html
- 
http://www.zope.org/Documentation/Books/ZopeBook/current/SimpleExamples.stx

Nicola might be right in me being wrong, i.e. that I'm focusing too much 
on the Cocoon website. If that is the case, I'm sorry, my view must be 
warped then.

> In the future, i would like block-specific documentation to remain 
> inside the blocks. Everything should remain as close as possible to the 
> code: javadocs, tests, metadata in general even documentation, 
> configurations, avalon roles, block metainfo and what not.
> 
> creating a single docu repository is, IMO, a very dangerous road because:
> 
> 1) it gives a perception that documents are maintained by somebody else. 
> This perception is already here and it's probably my fault and this is 
> causing pain and trouble to many people. I want this to be fixed in 
> order for the process to be more scalable.

I don't see the point in addressing a perception which surely isn't 
generalized. Some people like to work on docs, and they will, and the 
entrance barrier should be 'low enough' for them. Some people believe 
plenty of Javadoc will do the job, alas to be read only by co-developers 
IMHO. But we can't force anyone of them to become the other - we should 
support both styles.

Making Cocoon user documentation independent of Cocoon itself might be a 
good first step, that's why the Forrest transitioning is really, really 
good.

I agree I said something like 'we the doco people'. What I meant was the 
'people usually contributing to documentation'. Some of them are 
developers, some of them not.

My own belly tells me that people will write more and better user 
documentation if they get some proper playground. Having to worry about 
code sitting right beside their documents will not bring peace in their 
minds.

This all IMHO.

</Steven>
-- 
Steven Noels                            http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at            http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org                stevenn at apache.org


Mime
View raw message