Hello Simone, just to make it clear: my post was a general prevention warning for not falling into the "specification first hysteria", I absolutely understand your proposal is rather to document existing docs and I find this all right and welcome.
Raphaël Valyi http://www.akretion.com 2009/12/9 Simone Orsi <[email protected]> > Hi Raphaël, > I think you lost the point of my thread :) > > Raphaël Valyi wrote: > > By the way, > > > > Here is what the competitors are capable of with documentation: > > > http://wiki.openbravo.com/wiki/Functional_Documentation/ProductionManagement > > Would be great if we could have such functional diagrams too. > > That's true. > > > > > However, I would like to emphasis that unlike Openbravo leads seems to > > believe, open source just doesn't work like bullshit closed source. > > Specifying stuff and then paying anything that is required (or better > said: > > any cheap that will fit the budget) to get non outstanding developers to > > implement the spec in a non outstanding manner is not how sustainable > open > > source works. Sustainable open source works in first place when > > outstanding development is done, documentation is just a bonus, and in > our > > case a very welcome one. > > BTW, I recommend that good interview from DHH (Rails creator) where he > > states this once again: > > http://uxmagazine.com/strategy/less-is-better > > Citing: > "To me functional spec is a dead document. It's an illusion of > agreement. It's very, very easy for people to sit around a table and > just try to hash out what the program should do on a piece of paper." > > I agree with him. BUT, here, I'm not talking about specs for designing > the software. > > Here, if you read my doc, I'm trying to propose a default structure for > modules. That doc tries to point out that with some simple effort we can > make our modules better readable and understandable. > > > > > A bit like OpenERP, Openbravo recently outsourced to India, where > > low development costs fooled them (or their investors) into believing > they > > can shortcut how real sustainable open source development works and still > > remain competitive, which is not true when you consider the whole project > > ecosystem and life cycle (implementing a spec without have code and > > architecture quality at first place quickly lead to unmaintainable > > software). OpenERP had a better start, let's just hope they don't fall > into > > the same misconception. > > > > So, I'm all for documentation, by far we are lacking community processes > to > > elaborate module documentation, but still I want to warn those tempted by > > the spec first approach from the old waterfall proprietary methodology > that > > fail in the open source world. > > IMHO, this is not a "first spec approach" it's a "give modules some > basic structure and docs approach" ;) > > The test first approach however works and > > when tests become spec such as with Cucumber and OEScenario ( > > http://www.openobject.com/forum/topic13732.html ), the new test > framework by > > CampToCamp, then you have the best of the two worlds at work. > > This is true and I know very well how can be useful to have a strong > unit-test suite since I come from the plone world where we are used to > say "untested code is broken code". > > > My 2cts > > > > Raphaël Valyi > > http://www.akretion.com > > > > > > > > On Tue, Dec 8, 2009 at 5:36 PM, Simone Orsi <[email protected] > >wrote: > > > >> Simone Orsi wrote: > >>> Hi all, > >>> > >>> as almost every open-source project we lack of docs. > >>> > >>> The subject of this message "modules documentation" hence I will not > >>> talk about the reference manual (http://doc.openerp.com/developer/) > >>> which everybody knows it sucks... > >>> BTW: I'd prefers something like http://docs.repoze.org/bfg/1.2/...this > >>> is a *real* doc. > >>> But let's talk about that in a separate discussion. > >>> > >>> > >>> IMHO we *need* docs for modules' purpose and for modules' usage. > >>> > >>> I think all of us, noobs above all, spend (better, waste) too much time > >>> in searching and asking for the right module for this or that purpose. > >>> Even for people who want to approach OE this can be very very harmful. > >>> > >>> I think it would be nice to have a simple README.txt or HOW-TO.txt or > >>> whatever inside the module which tells you what the module does and how > >>> to get started with it. > >>> > >>> Also, the content of the *.txt should be placed into > >>> http://doc.openerp.com/technical_guide/ or into a nicer list of > modules. > >>> > >>> Cheers > >>> > >>> > >> Here's a draft: > >> > >> > >> > https://docs.google.com/Doc?docid=0ASJ1qTbr6NdMZG1oanhkN18wY3BncnJ0ZnE&hl=en > >> > >> > >> -- > >> Simone Orsi simone.orsi<at>domsense.com > >> Via Alliaudi, 19 - 10064 - Pinerolo (TO) - Italy > >> Mobile: (+39) 3475004046 - Fax: (+39) 01214469718 > >> Domsense Srl http://www.domsense.com > >> > >> _______________________________________________ > >> Mailing list: https://launchpad.net/~openerp-expert-framework > >> Post to : [email protected] > >> Unsubscribe : https://launchpad.net/~openerp-expert-framework > >> More help : https://help.launchpad.net/ListHelp > >> > > > > > -- > Simone Orsi simone.orsi<at>domsense.com > Via Alliaudi, 19 - 10064 - Pinerolo (TO) - Italy > Mobile: (+39) 3475004046 - Fax: (+39) 01214469718 > Domsense Srl http://www.domsense.com >
_______________________________________________ Mailing list: https://launchpad.net/~openerp-expert-framework Post to : [email protected] Unsubscribe : https://launchpad.net/~openerp-expert-framework More help : https://help.launchpad.net/ListHelp
