23

When writing documentation for a package aimed at CTAN, what should every manual contain? Specific examples of concise yet complete documentation are valued.

This is one of those (hopefully) big list questions, so please CW.

Richard Terrett
  • 3,381

2 Answers2

14

EDITED Based on helpful comments:

Standard sections to include (not necessarily in this order):

  1. Introduction

  2. Usage/Syntax/Examples

  3. Troubleshooting and Utilities

  4. Tips and related libraries/packages

  5. References and Index

Suggested sections (though not required):

  1. Table of Contents (depending on size of manual)

  2. Installation

  3. Implementation

For a specific example, my favorite is complete yet not concise whatsoever: The TikZ-PGF manual. That document is a work of art.

  • 3
    There's usually a section called, 'Implementation' which steps through the code. – cmhughes Oct 17 '11 at 04:37
  • Ah yes, you found the word I couldn't think of for step 4! –  Oct 17 '11 at 04:38
  • 1
    Step 4 may be called Usage, or Syntax, I think. And the implementation can be put at the end (before References and Indexes). – Leo Liu Oct 17 '11 at 05:14
  • 4
    I would leave out the complete code (as @LeoLiu mentions). No user of your package is interested in it, only programmers. And those are better off with a well documented source code, not the crappy DTX files that are hard to parse for the human brain (unless you are really used to them). – topskip Oct 17 '11 at 05:15
  • 1
    Usually you don't need a ToC for smaller packages, so 1. is the intro. I personally don't have an installation section, but it isn't a bad idea. However, installation is normally always the same (tex pkg.ins; latex pkg.dtx, copy the files where they belong) and is a little bit redundant. I would rather link to some external general installation guide (which is on my ToDo list). There should be a Usage section (often 2.) before the implementation section. Also Examples should come direct after Usage. The Implementation section is highly optional and should come at the very end. – Martin Scharrer Oct 17 '11 at 07:00
  • @MartinScharrer Good points. Installation and implementation may be better suited for a ReadMe file. When I think about it, my list is a combination of TeX, MATLAB, and R documentation styles. –  Oct 17 '11 at 12:27
  • Why a section "Installation"? It's different for every TeX distribution anyway. –  Oct 17 '11 at 14:43
  • @Patrick: No one can read .dtx files, but if you carefully document your code in them, the PDF documentation will contain a readable version. – Ryan Reich Oct 17 '11 at 15:38
  • 1
    @Axel: "Installation" is useful for people who either a) can't install into the distribution directory, or b) can't get the package from their distribution. Then they have to put it into ~/texmf, and how that is done is distribution-neutral. – Ryan Reich Oct 17 '11 at 15:39
  • “Usage/Syntax/Examples” surely stands head and shoulders above the rest of these. If the documentation includes this and pretty much nothing else, a package can still be usable (Mike Barr’s diagxy is an example of this). Without these, however good the rest is, I and I think many other users are left completely cold (I’ve come across this a few times, but never stuck with such packages long enough to remember them). – Peter LeFanu Lumsdaine Nov 08 '11 at 23:58
  • @RyanReich ~/texmf may be right for your system, but it is not right for many, many people. Installation sections encourage the belief that the user needs to install the package manually, which is usually not the case. (Exception: if you are publishing under a non-free licence, almost everyone will have to install manually, if they really want the package. So then it is a bit different.) – cfr Aug 02 '17 at 02:49
9

Some big projects with exceptional documentation:

Obviously, the demands are different for smaller projects, but bear in mind the things these projects do well...

As an example of the other end of the spectrum, here's a package that currently has fairly poor documentation: moreenum. (I am the author of it, so I can criticise it without anyone getting upset. Nowhere in the documentation have I really explained how to use the package. Now, it is a fairly simple package and it should be obvious. But I think it's better to spell everything out. I will add a brief section with some examples of usage to the docs in the next release.

Bobyandbob
  • 4,899
Seamus
  • 73,242
  • 2
    Honestly, the pgfmanual often does not explain which libraries are required for its examples. Also sometimes some infos about one thing are spread over different sections. IMHO, the memoir documentation is just too big for a just too big class. – Martin Scharrer Oct 17 '11 at 09:32
  • I like the pgfplots docu. It comes with many examples and often allows me to copy&pase code directly into my document. Also instead of a lengthy description about what a certain command does, an example often explains things straight away. The caption package docu comes with quite many of those simple examples that just show you what an option does. – Martin H Oct 17 '11 at 09:53
  • 1
    @MartinScharrer: Also, the pgfmanual index is really useless (as it tells you). – Ryan Reich Oct 17 '11 at 15:41
  • 4
    @RyanReich: Useless!!? It is the only way to find stuff there! ;-) – Martin Scharrer Oct 17 '11 at 15:42
  • 3
    @MartinScharrer: I want to defend the pgfmanual with regard to length; the generally useful TikZ reference is not at all long and the sections mostly contain what you think they will. The table of contents is well-described, too. However, it took me about a year to realize that you can use arbitrary math in coordinate expressions as long as you put braces around them, and for hiding this in the description of \path plot, the author cannot be forgiven :) – Ryan Reich Oct 17 '11 at 15:51
  • 3
    concerning the index: recent pgf versions are completely hyper-linked. In other words: you can safely search for any expression and click into the first encountered code example - it will almost surely lead to the definition of the word under the cursor. Together with the "back" button of most viewers (including acrobat!), this has the effect of a second index. Personally, I would not want to live without it. – Christian Feuersänger Oct 17 '11 at 17:38
  • 3
    I'll be flippant and remark that "An author should expect to be slapped around the face with a printout of the docs, bearing in mind that both papercuts and concussion are undesirable".

    (IMO TikZ would benefit from having 50% of the standard libraries thrown out into separate packages and cutting the backstory of the tutorials, making the pagecount slightly less silly.)

     – Ulrich Schwarz Oct 17 '11 at 18:03
  • 1
    The definition of the tikzpicture environment is on page 124 in subsection 12.2.1 'Creating a Picture Using an Environment' of section 12.2 'Creating a Picture' of chapter 12 'Hierarchical Structures: Package, Environments, Scopes, and Styles' of part III 'TikZ ist kein Zeichenprogramm'. Does anybody seriously fail to see the problem? – cfr May 10 '15 at 20:41