[Erp5-dev] Simulation and related issues documentation

[Łukasz Nowak]

HEllo,

On 2007-09-26, 13:13:25
Yoshinori Okuji <yo at nexedi.com> wrote:

> On Wednesday 26 September 2007 12:03, Łukasz Nowak wrote:
> > On ERP5's wiki there are some pages concerning simulation system -
> > Simulation Movements, Rules, Applied Rules, etc.
> >
> > While working with ERP5 I've get deeper and deeper into simulations
> > (but still not deep enough, of course ;) ) and I wonder if it would
> > be good to create wikipage which would document simulation - not as
> > discussions, which need deep knowledge, but as HowTo or other kind
> > of documentation-like page.
> >
> > Simulation documentation would describe why simulations are used,
> > what are its restrictions, how to analyse them, how they are used
> > in code.
> >
> > I'd like to startup that page. Please let me know what do you think
> > about it and what shall be such descriptive page name -
> > HowToSimulation does not sounds good for me.
> 
> It will be a Technical Note. Although it is a good idea to document 
> simulation, in my experience, it is so hard to teach others the
> simulation, even face-to-face. Making an usable document would be
> very tough and challenging.
> 
> I think there are three obstacles underlying in the simulation topic:
> 
> - The conceptual part. This is mostly about understanding business.
> This requires very consolidated examples which ordinary engineers
> understand easily (e.g. ordering -> invoicing). Good
> drawing/visualization is also required.

It is good starting point for "Simulation Documentation", isn't it?
Every beginner developer (just like me) would do anything to be able
to see and read some comments about such great, but cryptic, feature
as simulations. So such developer would be able to make faster progress
and do more contributions to system and *that* documentation.

> - The design part. The simulation contains so many actors that all
> newbies get upset. This is very difficult to explain in a
> comprehensive way, because one needs good understanding of several
> other parts of the system. Also, understanding "why things are
> designed in this way" requires describing many possible corner cases,
> and this is complicated enough (e.g. look at alex's discussion page).

But if simulations would be introduced in understandable way - even if
not complete form - it would be much easier to figure out discussion
and technical pages.

> - The implementation part. This is even more difficult, because there
> is a lot of code, and not every part is completely finished yet
> unfortunately, in the sense of "clean solutions". The simulation code
> is evolving all the time, and documentation would have to be
> frequently updated accordingly. For now, the only way I have found
> somehow effective is to ask one to work on a real implelentation
> little by little, and teach little by little. Reading documentation
> can give some hints, but not so effective in reality from my point of
> view.

Of course - it is the best way [tm] to do something with simulations
and ask directly more experienced developer. But as community would
arise around ERP5 project it would be very hard to spend time for such
newcomers.

> I can imagine that the "best simulation document" can be more than
> 300 pages in A4 papers, and this is not - maybe feasible but - hard
> to write up. So, probably, we need to start from some rather easy
> parts, especially, the conceptual part. "Why the simulation is
> good/useful/worth having" is not difficult to teach, if you have some
> good use cases. "How the simulation is designed" or "Why the
> simulation is designed in this way" is quite tough in documentation,
> and, for now, I have no idea of how to do this, without working
> together in real projects. If you have any good idea, I would like to
> listen.

I would buy a book "ERP5 Simulation Model Explained", how much it will
cost? ;)

So topic to start with would be "Why simulations are used in ERP5?" and
then "Now we will show you how to understand simulation-related code."?
 
> (Actually, the comments in the source code have a lot of useful
> information for the implementation part. If one does not hesitate to
> read the complicated code, I think it is possible to understand
> nearly everything. It simply consumes a lot of time and energy.)

Huh. And keep in mind, that simulation-related code is quite generic,
which do not help to understand how simulations work.

I *think* that it might be not so bad to
publicise screencast/screenshot/textize sessions with debugger inside of
expand() or some other simulation-related methods with comments. AFAIK
simulations are developer only - and if developer would be able to see
how to work with simulations he/she would be able to repeat those steps
her/himself to understand more and, of course, contribute his knowledge
do simulation-related documentation.

Thank you for such descriptive response - I see that I am not alone
with idea to document simulations.

I hope that "little by little" (as Beenhakker is saying) approach would
succeed.

As I'm going deeper and deeper with simulations I see it has more with
magic than with science - but that is normal with any new/innovative
technique. ;)

> Regards,
> YO

Regards,
Luke

-- 
Łukasz Nowak R&D Ventis http://www.ventis.com.pl/
tel: +48 32 768 16 85 fax: +48 32 392 10 61
``Use the Source, Luke...''