[SciPy-dev] user/misc.rst/ xxx

[David Goldsmith]

On Wed, Dec 16, 2009 at 7:35 PM, Pierre GM <pgmdevlist at gmail.com> wrote:
> On Dec 16, 2009, at 9:38 PM, David Goldsmith wrote:
>> The "Source" revision begins:
>>
>> "Miscellaneous
>>
>> Note XXX: This section is not yet written."
>>
>> and yet contains 5 sections and at least 100 lines of content.
>>
>> XXX indeed.  (Actually, I'd characterize it more as ???)
>
> Because it's not written indeed, just outlined. Nice outline, true, but nothing more than that yet,. Keep the warning in the content page of the user guide in mind.
> I'm surprised you haven't commented yet on the two 'Broadcasting' entries (the second should be byteswapping) ;) </tongueincheek>
>
> But more seriously, you raise a good point: most of the focus so far was on the reference, ie content automatically added from the docstrings, while the user guide is not as strong. Some reorganization is probably needed.
> In my mind, the reference is only that, a compendium of all the numpy objects (from functions to class attributes), while the user guide should present the various concepts behind numpy (type of arrays, dtypes, subclassing, broadcasting...). In other terms, part of what is currently in the reference could be ported to the user guide (but the user guide should systematically point to the reference)...
>

Pierre has kindly laid down the beginnings of an action plan (and here
I thought no one was paying attention to my little missives) - thank
you Pierre!  Any volunteers for a committee to flesh it out, e.g.,

* Identify portions which need reorganization, and provide
recommendations for how those portions should in fact be reorganized.

* Specify the concepts we want in the UG - especially any that aren't
already represented - including a brief statement for each as to why
they should be included, and what, more or less, an acceptable
presentation of them should cover/include.

* Identify what in the Ref. it makes sense to port to the UG and why
(and vice-versa to the extent that it might be appropriate).

* QA/QC for the UG systematically pointing to the Ref.

* Any other "items of guidance" writers/editors can refer to when
fulfilling these requirements.

(Just to be explicit about it, I see the "UG Action Plan Committee" as
a distinct entity, though of course it may not have an empty
intersection with the set "Writers/Editors").

Again, thanks Pierre!

DG