Ok.
Even though I think
- the tool (Doxygen, Wiki, plain files) is of no matter whether
documentation maintenance works out or not
- it is not possible to work offline with Wiki in contrast to git/Doxygen
I consider this mail thread closed. Wiki as the tool of choice if it is
not about API documentation.
Thanks so far for the hints.
I will come back with a first draft in Wiki, hopefully soon.
Carsten
On 04.09.2014 00:28, John Ralls wrote:
On Sep 3, 2014, at 8:07 AM, Carsten Rinke <carsten.ri...@gmx.de> wrote:
Hi,
what I (currently) have in mind is to use the Doxygen main page and related
pages for pulling together all sort of conceptional design info I can find (by
looking at the wiki, at html files from the tar ball, comments in the code,
hints from this mailing list, whatever).
So this would make up files used and written only for documentation, no mix
with code (like the currently available doxygen_mainpage.c file). Here I would
also like to add some pictures.
The rest (Modules, Data Structures, Files, etc.) should come directly from the
source files, basically as is.
Some source files contain quite a good implementation description.
Here the improvement that I currently see is to get the Modules in a more
'obvious' order, but I have not that this through yet, so I might actually skip
this.
Then I would think about whether the design descriptions could be brought into
the source files tree, so they end up as more detailed descriptions in Doxygen.
Again, not fully thought through. I am still in brainstorming mode to find a
way that makes access to the design easier for those not having worked as a
professional designers and programmers.
Something like this.
Basically this would remove the need to have a wiki as design documentation
source.
The opposite strategy is to not put any design info at all into Doxygen and do
it all in Wiki which I do not prefer if everything could done in one viewer.
That is the where you should stop me.
We’ve tried in-source design documentation, both in plain text files and in the
module descriptions in the Doxygen-docs. It wasn’t maintained. We don’t need to
repeat that experiment.
Let’s try moving it all to the wiki instead, and where appropriate link the API
documentation. That has the added advantage that you can update the design docs
directly without having to propose patches.
Both the Doxygen docs and the wiki are viewable in one viewer: The web browser.
They can even link to each other when that’s appropriate.
Remember as well the discussions about our goals for the next two dev cycles.
The design will change somewhat in support of those goals.
Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
