3

I've put together a basic package which I think could be useful, and is working great. The code is simple, and I want to submit to CTAN.

However, first, I have to write documentation, and I've never written documentation for anything before. Is there a guide to best practices for what is and isn't useful in outlining features and the source code? I've seen a lot of variety in TeX package documentation, and am not sure what level of detail or information needs to be in the PDF package.

(To be clear, I'm asking about guides to writing documentation content, not the technical aspects, which are well-addressed here What is good practice when preparing a package for CTAN? )

luaplaying
  • 127
  • 5
    Recollect which documentation you yourself found the most helpful (also consider addressee of your documentation: Is the package for other package authors? Then being more technical and concise is preferred. Is it for absolute beginners? Then you need to explain a lot without being too technical). Then reproduce in style what you found helpful yourself. For instance I find the first half of the pgfmanual is great for beginners and the second half is great for people programming (but I'd prefer if those two halves wouldn't be in the same document). – Skillmon Feb 17 '22 at 10:11
  • 4
    To give more examples in that direction: interface3 has a great interface documentation and is perfect for me, but it lacks introductory material for absolute beginners (a long standing issue with expl3 in general), but I'd hate if that introduction was added to interface3. I like acro and siunitx for their "for the impatient" sections. There is no general rule of what should be in the documentation. There are different levels of users, write the documentation for the level you expect to use the package. – Skillmon Feb 17 '22 at 10:14
  • 1
    (all of this comes from a user who doesn't consider himself good at writing documentation...) – Skillmon Feb 17 '22 at 10:17
  • 1
    Following from @Skillmon I think that there are two package users: those that just want to use the package to improve the typesetting of a document, and those who want to understand how it works. Probably the most important category is the first who want to know if it will help them and if so how to I use it. Many manuals are effectively written in two parts. Initially to end users about what the package provides and how to use it, and, optionally, to LaTeX programmers about how it works. I think that you have to decide who your audience is and produce what you would feel comfortable reading. – Peter Wilson Feb 17 '22 at 19:16

0 Answers0