> Bertrand Delacretaz wrote: >> David Crossley wrote: <snip/>
>> > The table that is at the top of example Wiki:FileGeneratorManPage would be >> > extracted >> > directly from the javadoc tags, and would be needed for both sets of >> > manpages. >> >> Yes, sounds good, this is definitely info that can be provided by developers. >> >> > It is important to get that information and also the >> > developer manpages done first, because they will form >> > the basis for the user manpages. The former should be >> > done by cocoon-dev and the latter can then be subsequently >> > done by anyone. I agree with pulling from the source code / javadocs anything that can be pulled. However I think that documentation for the developer audience is much less important right now than for the users. THe developers can realisticly be expected to delve in and read the code if they need to know. That just isn't a realistic expectation for the users though. >> >> Do we agree on what "user" and "developer" manpages are? > > Well spotted. This is very important to define up-front. Agreed...I think this should be defined in terms of the audience and the tasks and skills that would be reasonably expected for each.> >> For me: >> "user" is targeted at people using a component without modifying its java >> code >> >> "developer" would be targeted at people working on the component's code. > Agreed here. > And working on other components. I still do not understand how > my own code interacts with the rest of the wonderful Cocoon beast. > > Your definition is a good start but not quite there. > But this isn't really the point of this level of documentaiton, though I sympathize with teh challenge. >> And I think in this view "user" pages are much more urgent, many exist >> already but would >> benefit from being refactored into a well-structured set of manpages. > > Agreed. Agreed - as stated above. > >> I don't think developers have been complaining about lack of docs (the code >> is well >> structured and well written), but *users* are complaining often. > > I would complain if i was the type. I see serious lack > and inconsistency. Even the javadocs are not very good. > then the first step here is to start improving the javadocs. Once you have good javadocs, then worry aboutthe next level of developer documentation. > Rather i tried to encourage reference docs the last time > that Berni's proposal came up. > > I jumped straight in to open source as a Cocoon developer, > intending to patch as i learned. The "Dive in and learn on > the job" method has worked well. However, i was seriously > confused at the beginning and still am. I need well-structured > reliable developer documentation, even if is just the > one line definition of the component and its usage table. > We do need this, but I still think the users are more important. I can go look at the code, and figure out what I need to know. But it takes time, and I have people on the team who can't. > Actually, i am looking forward to these ensuing discussions > of each component and their parameters. Building the > documentation is where we will learn most. > Yep...and we'll probably find a few things to fix too... > --David -- "The heights of genius are only measurable by the depths of stupidity."
