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 <simone.orsi@xxxxxxxxxxxx
<mailto: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 <mailto: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
<https://docs.google.com/Doc?docid=0ASJ1qTbr6NdMZG1oanhkN18wY3BncnJ0ZnE&hl=en>
>>
>>
>> --
>> Simone Orsi simone.orsi<at>domsense.com
<http://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
<https://launchpad.net/%7Eopenerp-expert-framework>
>> Post to : openerp-expert-framework@xxxxxxxxxxxxxxxxxxx
<mailto:openerp-expert-framework@xxxxxxxxxxxxxxxxxxx>
>> Unsubscribe : https://launchpad.net/~openerp-expert-framework
<https://launchpad.net/%7Eopenerp-expert-framework>
>> More help : https://help.launchpad.net/ListHelp
>>
>
--
Simone Orsi simone.orsi<at>domsense.com
<http://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
