[Numpy-discussion] question about the documentation of linalg.solve

jh at physics.ucf.edu jh at physics.ucf.edu
Thu Nov 20 09:55:40 EST 2008


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 at 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--



More information about the NumPy-Discussion mailing list