[cctbxbb] Documentation .... again

[Jan Marten Simons]

Am Montag 10 Dezember 2012 23:52:26 schrieb Pavel Afonine:
> I've been having this plan too for quite some time, and yes, I've never
> had time to do anything (and most likely wouldn't in near future).
> However doing it collectively may cut on amount of time and effort, thus
> making it practical in the end.
> 
> I would plan it first. To start, I would say we need:
> 
> 1) find out who wants to participate;
> 2) write a framework and agree on it. I see it as a list of bullet
> points outlining the subjects that we are going to cover.
> 3) then we see who wants (and can) to cover what and do the first step:
> everybody fills in his/her contribution.
> 4) then we collectively review the whole thing, and do a few iterations
> of that until we are satisfied with what we have.
> 
> Additional thoughts:
> 
> I know it may make things slightly more complex, but I suggest that we
> make sure that every example provided in the tutorial is exercised as
> part of our routine tests. This will ensure that the effort we are going
> to invest will not be obsoleted shortly after it's complete. Also, this
> would imply the document may change if a cctbx functionality described
> in it changed (so it's not a static paper). I did this for command line
> version of phenix.refine several years ago, and it seems to work well
> (though I'm not saying that we should do it the same way for this
> tutorial!).
> 
> I have zero experience with Google Docs, so these couple of questions
> are rather out of my ignorance. Does it allow to 1) insert formulas, 2)
> put pieces of code that can be extracted automatically for exercising ?

Maybe I'm a little late to add to the discussion, but I think doing this as a 
wikibooks[1] project would be best. That way it can easily be found by people, 
a large user base can easily participate and the hosting is of no concern to 
us. Also LaTeX style formulas are available.

[1] http://en.wikibooks.org/wiki/Subject:Science

With regards,

 Dipl. Phys.
  Jan M. Simons
 
Institute of Crystallography
RWTH Aachen University