[cctbxbb] Documentation .... again

[Pavel Afonine]

Hi Graeme,

sounds reasonable and makes sense to me. Perhaps our collective 
knowledge is enough to document everything, but it's a good idea to not 
do it at once but incrementally upon request/need.

Pavel

On 12/7/12 1:59 AM, Graeme.Winter at diamond.ac.uk wrote:
>
> 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
>
>
>
>
> _______________________________________________
> cctbxbb mailing list
> cctbxbb at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb

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