openerp-expert-framework team mailing list archive

[Raphaël Valyi <rvalyi@xxxxxxxxx>]

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>

> 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
>