On Thu, Nov 20, 2008 at 07:58:52AM +0200, Scott Sinclair wrote:

A Notes section giving an overview of the algorithm has been added to the docstring http://docs.scipy.org/numpy/docs/numpy.linalg.linalg.solve/.

Doc goals: We would like each function and class to have docs that compare favorably to those of all our competitors, and some (notably Matlab) have very good docs. For our effort, this means (at the very least):

- readable by a user one level below the likely user of the item (i.e., they can read the doc and at least learn the type of use it might be for, so that in the future they know where to go) - complete with regard to both inputs/outputs and methodology - referenced to the literature, particularly in cases where the methods employed impose limitations for certain cases - both simple examples and some that show more complex cases, particularly if the item is designed to work with other routines

There was a big push over the summer, and a large number of people pitched in, plowing through the list of undocumented functions and writing. However, many of the functions that remain are not amenable to this approach because they require specialist attention to document methodology that not everyone is familiar with. This will be a dominant issue when we start documenting scipy.

So (everyone), if you identify a routine in your specialty that requires a doc, please either hop over to docs.scipy.org and start writing, or post a message on scipy-dev@scipy.org asking to team up with a writer. For convenience, the doc wiki contains links to the sources so you can easily look at the functions you are working on. Even simply adding something in the Notes section about the method (as was done in this case), putting in a a reference, or giving a non-trivial example will provide material for other writers to flesh out a full doc for the routine.

Thanks everyone for your help!

--jh--