1
Vote

Documentation

description

Hallo !
I have seen the new site (http://nanapro.org/) and the new documentation by Jean-Baptiste.
They looks great !
Sometimes I do not receive notifications on news (I have to revise all my subscription options), and have not seen the post https://sourceforge.net/p/nanapro/blog/2013/12/nana-documentation-wants-your-help/ . So, I'm late...
Some time a year ago I printed the Nana docs to learn about it. This is a .docx file (now a .odt). And I wanted to talk about.
I can see different kind of docs and this is what I think about it:
The “official”: (author driven)
A general docs. Generated independent of the nana source code. It is somewhat stable and therefor approximately bind-ed to some nana version. It roughly correspond to what was at http://nanapro.sourceforge.net/help/index.htm (now not working – could it contain a link to a new site?). It is now http://nanapro.org/help/html/index.html and is wonderful. The sources are now accessible for everyone who want to collaborate directly on each page, or all together in https://nanapro.codeplex.com/SourceControl/network/forks/jbksql/nanadoc/latest . (It will be best to be set also into the nanapro::master... just to make me ease to fetch it and merge with my working code). I think, with some automation it could be possible to convert into a printable book.
This is “official” and the sources are controlled by the authors, while any collaborator can contribute. This is perfect.
The “detailed” and current reference: (code driven)
Automatically generated from the nana source code by Doxigen. Not binded to a version, but to the “current” branch each want to document. It is provided in form of comment in the code and a “few” additional .markdonw files, also in the source code tree. It is automatically generated and not so pretty and “theme-able” as the official. I have something , and I propose to incorporate to the nanapro::master branch too. It will be very nice too, to have a working version of this reference for nana::master somewhere installed. I see CodePlex have a tab Documentation, with seem to be a good place for that... but I'm not sure (it is automatic generated, so, DONT need a version-control on it!).
I think the best reference - documentation is a well written code, with a few comment. So, I encourage to write as few and as short comments as possible, and rely more on good names. For example, in function declaration always name each argument with a possible long and meaningful name.
A wiki: (community driven).
Some projects had a wiki, for example in sourceforge. I have no idea how difficult is to set -up one, and even not much experience using it. But I guess it is the easier way to contribute, even for “occasional” contributors with don’t want to fork the code of nana or the documentation, but simply correct some error or quickly add some ideas. Also is a good place for discussion. Originally completely filled from the others will sometime used to set back the others docs. It can be still be moderated by the author.
Thank for your patience !

file attachments

comments