[cctbxbb] Documentation .... again
Pavel Afonine
pafonine at lbl.gov
Fri Dec 7 02:09:53 PST 2012
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>
More information about the cctbxbb
mailing list