<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <div class="moz-cite-prefix">Hi Graeme,<br>
      <br>
      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.<br>
      <br>
      Pavel<br>
      <br>
      On 12/7/12 1:59 AM, <a class="moz-txt-link-abbreviated" href="mailto:Graeme.Winter@diamond.ac.uk">Graeme.Winter@diamond.ac.uk</a> wrote:<br>
    </div>
    <blockquote
cite="mid:13999B6FC038EB44B067771E3CFBD09152A6D9CF@EXCHMBX02.fed.cclrc.ac.uk"
      type="cite">
      <meta http-equiv="Content-Type" content="text/html;
        charset=ISO-8859-1">
      <meta name="Generator" content="Microsoft Word 12 (filtered
        medium)">
      <style><!--
/* Font Definitions */
@font-face
        {font-family:Calibri;
        panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
        {margin:0cm;
        margin-bottom:.0001pt;
        font-size:11.0pt;
        font-family:"Calibri","sans-serif";}
a:link, span.MsoHyperlink
        {mso-style-priority:99;
        color:blue;
        text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
        {mso-style-priority:99;
        color:purple;
        text-decoration:underline;}
span.EmailStyle17
        {mso-style-type:personal-compose;
        font-family:"Calibri","sans-serif";
        color:windowtext;}
.MsoChpDefault
        {mso-style-type:export-only;}
@page WordSection1
        {size:612.0pt 792.0pt;
        margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
        {page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
      <div class="WordSection1">
        <p class="MsoNormal">Hi Folks,<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">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 &#8211; this is fine and well understood. <o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">As a kind of &#8220;patch&#8221; 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:<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">cctbx_project/cctbx/xray/structure.py<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">&#8230;<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">&nbsp; def structure_factors(self,
          anomalous_flag=None, d_min=None,<o:p></o:p></p>
        <p class="MsoNormal">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
          algorithm=None,<o:p></o:p></p>
        <p class="MsoNormal">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
          cos_sin_table=False,<o:p></o:p></p>
        <p class="MsoNormal">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
          quality_factor=None,<o:p></o:p></p>
        <p class="MsoNormal">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; u_base=None,<o:p></o:p></p>
        <p class="MsoNormal">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; b_base=None,<o:p></o:p></p>
        <p class="MsoNormal">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
          &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;wing_cutoff=None):<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">what is cos_sin_table for? with things like
          this there is the attitude that it is safe to ignore, however
          if we&#8217;re writing code to guide people&#8217;s experiments it would
          be good to be sure of this. Some simple documentation
          explaining this would be very useful.<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">I&#8217;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 &#8211; perhaps the way that stackoverflow works, or
          an email, or something really lightweight. Even this mailing
          list could be used I guess?<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">I would be happy to help with this, though
          the above example is not one where I know the answer!<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">Thoughts?<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">Best wishes,<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal">Graeme<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
        <p class="MsoNormal"><span
style="font-size:10.0pt;font-family:&quot;Arial&quot;,&quot;sans-serif&quot;">Dr.
            Graeme Winter</span><o:p></o:p></p>
        <p class="MsoNormal"><span
style="font-size:10.0pt;font-family:&quot;Arial&quot;,&quot;sans-serif&quot;">Senior
            Software Scientist</span><o:p></o:p></p>
        <p class="MsoNormal"><span
style="font-size:10.0pt;font-family:&quot;Arial&quot;,&quot;sans-serif&quot;">Diamond
            Light Source</span><o:p></o:p></p>
        <p class="MsoNormal">&nbsp;<o:p></o:p></p>
        <p class="MsoNormal"><span
style="font-size:10.0pt;font-family:&quot;Arial&quot;,&quot;sans-serif&quot;">+44
            1235 778091 (work)</span><o:p></o:p></p>
        <p class="MsoNormal"><span
style="font-size:10.0pt;font-family:&quot;Arial&quot;,&quot;sans-serif&quot;">+44
            7786 662784 (work mobile)</span><o:p></o:p></p>
        <p class="MsoNormal">&nbsp;<o:p></o:p></p>
        <p class="MsoNormal"><o:p>&nbsp;</o:p></p>
      </div>
      <br>
      <p align="justify">&nbsp;</p>
      <p align="justify">--&nbsp; </p>
      <p align="justify">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.<br>
        Any opinions expressed within this e-mail are those of the
        individual and not necessarily of Diamond Light Source Ltd. <br>
        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.<br>
        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<br>
        &nbsp;</p>
      <br>
      <br>
      <fieldset class="mimeAttachmentHeader"></fieldset>
      <br>
      <pre wrap="">_______________________________________________
cctbxbb mailing list
<a class="moz-txt-link-abbreviated" href="mailto:cctbxbb@phenix-online.org">cctbxbb@phenix-online.org</a>
<a class="moz-txt-link-freetext" href="http://phenix-online.org/mailman/listinfo/cctbxbb">http://phenix-online.org/mailman/listinfo/cctbxbb</a>
</pre>
    </blockquote>
    <br>
  </body>
</html>