[Ktechlab-devel] Time for a clear route forward?

[P Zoltan]

  Here comes a longer answer:

On Fri, 06 Nov 2009 14:45:55 +0100, Matthew Ayres  
<solar.granulation at gmail.com> wrote:

> Hello all you lovely devs!
>
> I've been using KTechLab on and off for a while and, watching this
> list, am somewhat concerned.  Not least because so few seem to
> understand the code that's been written.  So, as someone not without
> experience in software projects, I decided to add my tuppence worth.
> It may be just that little, of course.
>
> Mainly, I'm wondering whether serious consideration has ever been
> given to full documentation of this project with flow charts and
> what-have you.  The goals of KTechLab are lofty and surely, SURELY, it
> would aide developers old & new to have a central set of documentation
> detailing both the current state and function of the code, classes,
> interfaces etc. as well as where it should be heading.  No?

  I totally agree.

>
> Before I have seen such suggestions as I am about to make, in other
> projects, be rejected out of hand but I would like to think that in
> such a project as this it would be worth considering deeply.  My
> suggestion is that code modification be put on hold for perhaps a
> month or two (with a clear deadline laid down), while people work
> together to create the documentation to which I allude.

  Functional modification should be stopped; In my opinion using doxygen to  
generate documentation about classes/implementation is one way to go,  
beacuse it's "at hand" when somebody modifies the code, documentation can  
be also updated. So it would be a good start to have useful documentation  
comments for each class and method. Plus documents about the big picture,  
to see how all these classes integrate.

>
> Those who know enough about electronics, as well as those with a good
> grasp on OOP and Good Practice, could brainstorm together and create a
> fully formed set of flowcharts and related documents detailing how the
> system should work.

  I'm setting up a wiki on sourceforge, as main storage for documentation.  
If someone else has different opinion about where the documentation should  
be stored, feel free to write on the list.

  About the configuration of wiki: I want to make it free (to write) as  
possible, but the old wiki has got regularly spammed. More news to come.


>
> Those who enjoy examining existing code could simultaneously create
> current-state documentation.

  The existing documentation attempts can be found here:

- old ktechlab wiki (the pictures and some formatting is missing, but it's  
a good start):

http://zotanp.extra.hu/wikki/index.php/Main_Page

  especially the developer section:

http://zotanp.extra.hu/wikki/index.php/Index:Dev

- documents written by myself, look around here:

https://sourceforge.net/userapps/trac/zoltan_padrah/


Also the doxygen documentation generated from the source code can be  
useful.



>
> Compare and contrast, solving the engine's issues all at once and
> coding them to match.  Perhaps this would even be a good time to
> separate the simulator components from the display components, so that
> overhaul of the former and porting of the latter to KDE4 could proceed
> at appropriate rates.  Then the GUI need only have a clear set of
> interfaces with the engine, which also opens the doors for specialised
> GUIs in Gnome and other environments.
>


  Again, I agree.


> Please, consider it.
>
> -Matthew Ayres
>