On Sat, 2005-05-14 at 09:47 +0200, z3lab-request at lists.nuxeo.com wrote: > Message: 9 > Date: Sat, 14 May 2005 09:47:54 +0200 > From: Paul Everitt <paul at zope-europe.org> > Subject: Re: [Z3lab] portal specifications > To: Martijn Faassen <faassen at infrae.com> > Cc: z3lab at lists.nuxeo.com > Message-ID: <A2840DC6-E6A6-412B-975F-569AD892221B at zope-europe.org> > Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed > > > Disadvantages > > > > * higher barrier to entry for J. Random Open Source Developer > > > > * harder to do simple 'diff' to see what changed Aside to Martijn: 'diff' is not necessarily an advantage when it comes to large chunks of prose, it's not good showing the lots of little changes that an editor would make in one pass, OO (and Word's) change management systems are better visually and add more features like accept/reject on a change by change basis. > Very good writeup of the pros and cons. I agree. > I propose that we tolerate both approaches. Ultimately I think > Martijn's view will prove right, that developers will jot things down > in an Emacs buffer as they are writing code. Yeah, although I would say leverage and not tolerate. For component design docs doctests are pretty superior (I recently got a good example of this learning the Zope 3 catalog and its doctest) for designing, testing and learning the thing, lots of bang for one buck. For overall design, user and feel-good docs nothing beets a good ol' chapter outline developed into a chapter with technical and copy editing. For this a tool like OO is more apropriate, although you can get by with text in svn, it's a big hurdle for a copy editor to jump. Martijn's reference to the dogbowl is important. We should avoid those mistakes, but I don't have an answer for that one. CPS may be fine french cuisine compared to dog food, but if we start using it to write doctests then we're getting it wrong. On the flipside, if CPS has cool OO integration then we can leverage that to write prose-based material that needs polish. If we are writing that stuff in raw XML then we are getting wrong again. > However, I'm personally interested in the OO.o/Docbook approach the > Julien described and will use it as soon as he gives me a login. > > Moreover, I think we should recognize Julien and Jean-Marc's > initiative, just like we should recognize Philipp's initiative. I > think the two directions can work together. Yeah I like the screenshots! -Michel
Hosting: Nuxeo: Zope service provider