Advice to developers, by Robert Dodier

Disclaimer: I have no special authority to tell other people what to do.

  1. Participation in the mailing list is encouraged.

  2. Modifying maxima/src

    1. First, do no harm.
    2. Exercise care and good taste.
    3. Changes which modify the way something or anything works from the point of view of the user need to be mentioned on the mailing list.
    4. Don't be afraid to make changes, but don't be surprised if other people ask you to redo / undo changes you've made. Changes which cause make / make install / run_testsuite to fail are always unpopular.
    5. When you commit something, make an informative log message. If you change more than one file, commit them all with one "cvs commit" and mention each file in the log message.

  3. User documentation style guide

    1. Get to the point. Make the text clear and concise.
    2. Describe what Maxima does. Do not describe what the user can do with Maxima. Do not address the reader as "you".

    3. Organize documentation as follows.

      1. First sentence summarizes the topic.
      2. Put the exposition before examples. Do not mix examples into the exposition.
      3. Put an examples section after the exposition. It is often useful to recapitulate the exposition in the examples section.
    4. Make each documentation unit self-contained. Don't define one item in terms of another. Repetition is OK because people rarely read computer manuals from beginning to end.
    5. References to books, articles, etc are good.
    6. To make a texinfo document for a share package, copy maxima/share/template.texi and paste in your text. See also README.developers-howto on this point.
    7. The Common Lisp Hyperspec is a suitable model for Maxima documentation. I don't mean to suggest slavish imitation.