IMP documentation & tutorials by the people
Hey guys, Here is a very tempting suggestion, which might benefit all of us in the long run, but will require some group effort :) As we all know, though lots of efforts have been made to document IMP, getting started on IMP development or usage is (quite naturally) still somewhat far from obvious (missing or outdated documentation or examples, no tutorials etc.). So - the idea is that if we team up, we can improve the documentation and write tutorials in relatively small effort, benefiting new users and developers, and surely also old ones. We can then have peer-reviewing of the resulting documentation (e.g., one team checking the documentation / tutorials written by another team).
Here are some initial ideas Daniel and I had in mind, and feel free to add suggestions: * A team will make sure the Getting Started and Developer Guide are up to date, make them even friendlier and extend them further * Other teams will validate existing example codes, add missing example codes, and most important, write friendly tutorials on how to accomplish common IMP tasks (both development, e.g., "how to write new code for Monte-Carlo simulation with restraints", and usage e.g. "how to dock from EM") * Perhaps one team can also go over some key classes and improve their code documentation, especially in the core / kernel / base / atom modules.
Ok, Who's in? :) We will try to keep the task relatively smalls, so that they can be done in 1-2 working days.
Cheers, Barak
> > * Perhaps one team can also go over some key classes and improve their > code documentation, especially in the core / kernel / base / atom modules. > I suggest a beautiful method to do this. Use WARN_IF_UNDOCUMENTED from doxygen, and a simple rule: Warning, then failed commit. I would find it quite more useful that common existing rules that are just sugar: 80 characters line, python indentation, blah, blah.
On 07/18/2012 12:55 PM, Javier Velazquez-Muriel wrote: > I suggest a beautiful method to do this. Use WARN_IF_UNDOCUMENTED from > doxygen, and a simple rule: Warning, then failed commit.
Well, that isn't that difficult to implement... but it doesn't force people to write useful documentation (it just forces people to make the check happy by adding /** xxx */ to every function).
Ben
On 7/18/12 12:59 PM, Ben Webb wrote: > On 07/18/2012 12:55 PM, Javier Velazquez-Muriel wrote: >> I suggest a beautiful method to do this. Use WARN_IF_UNDOCUMENTED from >> doxygen, and a simple rule: Warning, then failed commit. > > Well, that isn't that difficult to implement... but it doesn't force > people to write useful documentation (it just forces people to make > the check happy by adding /** xxx */ to every function). > > Ben
Well, this is documentation indeed. It should be read as: "I didn't bother". I'm not saying that all functions, even the trivial ones should be documented. As usual, common sense applies . A function add_one_to_number(number) does not need documentation. Well, then document /** obvious */. It is no asking for too much.
participants (3)
-
Barak Raveh
-
Ben Webb
-
Javier Velazquez-Muriel