On the example/tutorial distinction: I don't see that there is a clear difference between "a very short piece of code solely intended to highlight the very specific aspect " and "A fully step by step documented script or series of scripts, intended to fully explain the usage of one or several IMP aspects". I would expect that any example provides a full step-by-step explanation of what it is trying to show (and is definitely trying to show one or more of IMPs aspects).
In my experience, software tutorials (in contrast to examples) generally refer to something that is primarily text or a video or a lecture (presumably including lots of bits of code). As such, a well documented piece of source or set of sources and data doesn't really fit the definition (but Keren and Ben's tutorial does). In contrast an example is a piece of code which some text inserted in it. Under this split, each tutorial would have accompanying example code, which could go with other example code (since it works fine as "just" example code in addition to be referred to in the tutorial).
Open questions:
- where to put multi-module example code: I've been saying it should just go into a module or the kernel. We can always add a list of examples referencing a given module, and I'll bet we can do that on a class/function level given a little time. Actually that would be pretty awesome: have a automatically generated list, for each class/function, what examples use it.
- what to do with tutorial text and videos as well as other IMP-related publications. Perhaps have a publications directory?
- I really don't really like the "applications" name either, but do like it better than the alternatives we have so far. Keren and I had discussed having a subdir of applications called "utilities" which were just random little useful scripts. I'm not sure these names really matter as long as they are documented (which they currently are not).
Minor comments:
- examples are currently installed with the documentation
- I don't really like have example code that is just a snippet of code since then there is no way to have the code run automatically. And, in my experience, when code is not run, bit rot tends to set in.
- Examples : a very short piece of code solely intended to highlight the very specific aspect it exemplifies (e.g. the sample code on the ConnectivityRestraint html page).
If I understand it well, examples are actually found in modules/example subdirectories only in the svn source dir (i.e. not in the installed dir), and automatically included in the manual pages. I think it is OK like that, though it might be useful to let the user install examples as well, maybe in a distinct directory (share/examples/modules/ ?).
- Applications : utility scripts and binaries developed on top of IMP (fox application, multifit scripts, scripts to transform coordinates of atoms in a PDB file)
I am not sure I like the term 'application' because it is somehow ambiguous and could be read as 'application of IMP', thus biasing expectations towards 'examples', 'tutorials', 'exercises', or 'biological applications'. As a replacement I would suggest softwares, binaries, utilities, executables… Anyway, this is probably a matter of taste, and any choice is good as long as the definitions are documented (for instance on the first page of the manual).
I don't know also if it would not make sense to discriminate between 'utilities' (isolated scripts or binaries that can be used to achieve useful tasks in various situations, such as the transformations of coods for ATOMS in a PDB file) and plain 'software' (more connoted to a dedicated application : fox and multifit binaries), and maybe sort scripts in subdirectories for each distinct softwares so as to make clear for instance what belongs to the multifit protocol etc…
- biological_systems : all scripts and data that where used in a published paper
Once again, I am not really keen on the term, but this time because I think it is not descriptive enough. Maybe biological applications would suit better. Also, it would be worth making clear the goals of this directory : providing examples of IMP usage in real life applications ? Providing base scripts that can be modified by users for testings/understanding how IMP works ? Providing a repository to ease re-run and verification of published works ? ...
I would also add tutorials :
- Tutorials : A fully step by step documented script or series of scripts, intended to fully explain the usage of one or several IMP aspects. Writing tutorials is probably time consuming and notw gratifying at all, it is nonetheless critical to help people find their way among the main directions of a tentacular project such as IMP. I'll try and make my first "groping and discovering" scripts into a first tutorial that I'll place in the IMP wiki.
Le 5 nov. 2010 à 22:54, Daniel Russel a écrit :
Next version of the proposal: - mudulename/bin becomes internal, undocumented, utility executables (eg the benchmarks). They will not get installed in build/bin or installed at all with imp. protein_ligand_score gets moved to
- applications which has executables that users are supposed to see (we will add facility to document the applications in a similar manner to how modules are currently documented). The code is not expected to be read by random users and the applications will get build into build/bin and installed in bin.
- a new directory, biological_systems will be added. In there will be scripts with data that have been published in separate papers about the biological system in question, The scripts should be written so as to be readable and modifiable by others.
Comments?
_______________________________________________ IMP-dev mailing list "> https://salilab.org/mailman/listinfo/imp-dev