[Erp5-dev] Simulation and related issues documentation

[Yoshinori Okuji]

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.

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

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

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.

(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.)

Regards,
YO
-- 
Yoshinori Okuji, Nexedi CTO
Nexedi: Consulting and Development of Free / Open Source Software
http://www.nexedi.com
ERP5: Full Featured High End Open Source ERP
http://www.erp5.com
ERP5 Wiki: Developer Zone for ERP5 Community
http://www.erp5.org