openerp-expert-framework team mailing list archive

[Simone Orsi <simone.orsi@xxxxxxxxxxxx>]

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 <simone.orsi@xxxxxxxxxxxx>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     : openerp-expert-framework@xxxxxxxxxxxxxxxxxxx
>> 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