[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] documentation standards?

From: daly
Subject: Re: [Axiom-developer] documentation standards?
Date: Wed, 22 Oct 2014 00:09:15 -0500

>     Yes I learned some time ago that maintenance can be devastating.
>I am a little at odds with your theory but not too much; and I will
>try to conform to your styles.  Along that vein: can you point me to
>the current tools you recommend and examples of how you are currently
>doing documentation?  They seem to have drifted a little over the

All of this is optional guidance. The goal is to improve Axiom so that
it can be maintained, modified, and extended by the next generation.
I hope it can eventually be used as primary teaching material for the
next generation of computational mathematicians.

The documentation is "self-organizing" as more of it gets added so
it is likely to continue to "drift". There isn't any "style" to
conform to as you will be one of the first people to generate docs.

Tools? Emacs. latex. Quicktime for videos. latexdraw for diagrams.
graphviz for graphs. I try to minimize using new latex packages so
users do not have to install anything.

There are three kinds of documentation currently being used in Axiom.

  1) literature references (all books have a biblio section now)

  2) domain specific ideas, equations, special terms, etc (Volume 10.1)

  3) "WHY did you write code that way" (in code-containing vols such as
     5: interpreter, 9: compiler, 10.2: categories, 10.3: domains,
     10.4: packages, 10.5: numerics, etc.) directly associated with
     the code.

The first is literature references. I have a collection of papers
for some of the references in the bibliography book (the way to tell
is to look for the keyword entry 

   paper = "NameYY.pdf"

in the bibtex entry). When I find a copy of a paper I try to include
the abstract from the paper. Ralf found a style that allows the
abstract to be included in the bibliography section of the books. That
makes it easier to know if a reference might contain something useful.

The down side of literature references is that obtaining some of
them can be expensive (e.g. Luke's 2 volumes were $150) and some
of them simply are not available (e.g Brillhart's PhD thesis).

URLs to online copies would be really appreciated. I know it is asking
too much but you could really make my day by including the abstracts
so I don't have to hunt down the papers :-)

The second, more specific documentation, is a page or so of theory so
that a beginner has some clue about the maths that your code depends
on (e.g. Umbral calculus). It doesn't have to have a lot of background
but it ought to be slanted toward an overview you'd give to a mathematician
who is new to your subject. The likely audience is a mathematician trying
to write new code or using your domain. Clarity and brevity matter.

Write the ideas (e.g. a dhmatrix is used to perform rotations,
translations, and scaling) rather than the heavy theory (e.g.
theorems, lemmas, proofs, etc). Include references so readers have a
gateway to important literature if they want more.

This second form of documentation will be a separate chapter or
section or be merged into some existing chapter or section of Volume
10: Axiom Algebra Theory. This book is intended to be an overview of
the subjects that Axiom covers so that people can understand where to
look for things and what might be available in Axiom.

An excellent example would be Weisstein's pages (DO NOT COPY THEM), e.g
Realistically speaking, ANYTHING that gives an Axiom user a clue about
your domain would be most welcome.

Save the user from doing a literature crawl to figure out why you use
a matrix argument to construct Quaternions when none of the usual
presentations even mentions the idea.

The third form of documentation is "Why did you write this code
the way you wrote it?". This is NOT intended to be a line by line
explanation but rather to explain things which are painfully 
obvious to your PhD committee but nobody else. 

A recent example is the Bernoulli code. If the author had said

  "This implements the formula: \sum_{p=1}^n ....
   where the outer loop counter is p. Since odd Bernoulli numbers 
   are always 0 I collapsed the inner loop to only compute even
   numbered terms. So the inner loop equations for "t" and "b"
   are derived from the above formula into a more efficient form by
        .... (show how the t and b formulas used came from
              the formula above so the clever code makes sense)...

It is usually the case that, being an expert in a domain, you know
the most efficient, most clever, most compact ways of writing code.
But nobody else has a clue. Give them a clue WHY you wrote the
clever parts the way you did. 

Give the maintainers a clue about what you might depend on. When the
algebra gets reorganized and your code breaks the maintainer has to
"re-derive" WHY you were cleverly groveling through the Lisp
representation of another domain.

The "maintainer" could be YOU a few years from now and you probably
won't remember why
was such a clever hack.

I know all of that seems like a lot but actually it mostly amounts to
a ratio of a few lines of words for each line of code. A one page Spad
domain would likely generate two literature references, a page of
"intro-theory" and a couple paragraphs of "WHY" for the clever parts.

For the future....

Think of it as generating slides for a talk about your domain.

I'm starting to include videos and pondering per-domain presentations.
Think of them as "TED Talks" for Axiom users and developers.

The plan is to include hyperlinks from the books to the videos.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]