Simone,
since small changes are usually better then large changes, from your
draft specification, why not focus on the README.txt?
At least, it should contain:
- name of the module
- the purpose of the module
- the author/maintainers
- the framework capability it provides,
- the new processes it implements,
- the existing processes it changes,
- the vertical implementation if applicable
It might be out of the scope of this discussion, but it would be very
helpful when talking about business processes, to specify the process in
human language or diagram. I really believe this "process orientation"
when documenting modules is good since both business people and
developers understand about processes.
Regards,
CJ
PS: I'm a bit overwhelmed this end of year, but I plan to propose a
framework for integrating OE with external systems in January.
Raphaël Valyi escreveu:
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]
<mailto:[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] <mailto:[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
<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 : [email protected]
<mailto:[email protected]>
>> 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 : [email protected]
Unsubscribe : https://launchpad.net/~openerp-expert-framework
More help : https://help.launchpad.net/ListHelp
_______________________________________________
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
