Tell me more ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.
up vote 18 down vote favorite
2

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.

share|improve this question

2 Answers

up vote 10 down vote

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.

share|improve this answer
3  
There's usually a section called, 'Implementation' which steps through the code. – cmhughes Oct 17 '11 at 4:37
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 5:14
3  
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). – dıʞsdoʇ Oct 17 '11 at 5: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 7:00
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
show 5 more comments
up vote 9 down vote

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.

share|improve this answer
1  
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 9:32
2  
@RyanReich: Useless!!? It is the only way to find stuff there! ;-) – Martin Scharrer♦ Oct 17 '11 at 15:42
1  
@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
1  
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
1  
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
show 2 more comments

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.