[cctbxbb] Documentation .... again

[Graeme.Winter at diamond.ac.uk]

Hi Folks,

Been thinking some more about the old chestnut of documentation. The lack thereof is a well understood issue, and to be honest one which is not going to change any time soon as no one has the time to maintain a manual - this is fine and well understood.

As a kind of "patch" for this I was wondering if it would be possible to have a forum where someone could ask for e.g. documentation for a currently undocumented function, which could then be added to the subversion in the code itself. For example:

cctbx_project/cctbx/xray/structure.py

...

  def structure_factors(self, anomalous_flag=None, d_min=None,
                              algorithm=None,
                              cos_sin_table=False,
                              quality_factor=None,
                              u_base=None,
                              b_base=None,
                              wing_cutoff=None):

what is cos_sin_table for? with things like this there is the attitude that it is safe to ignore, however if we're writing code to guide people's experiments it would be good to be sure of this. Some simple documentation explaining this would be very useful.

I'm definitely not suggesting (i) that anyone writes a manual or (ii) that all undocumented functions are suddenly documented, only that there is a mechanism set up that someone could ask about this and that someone who knows the answer could commit the changes to cctbx and then reply with the diffs - perhaps the way that stackoverflow works, or an email, or something really lightweight. Even this mailing list could be used I guess?

I would be happy to help with this, though the above example is not one where I know the answer!

Thoughts?

Best wishes,

Graeme

Dr. Graeme Winter
Senior Software Scientist
Diamond Light Source

+44 1235 778091 (work)
+44 7786 662784 (work mobile)





-- 

This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.

Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd. 

Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.

Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom

 







-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20121207/449411d2/attachment.htm>