Tags about documentation

Question

At the moment we have three tags concerning documents about TeX: books, manuals and documentation. The only one with a wiki is books, which says that it “is for questions which deal with books about TeX, LaTeX and other topics of this site.”

I just brought this up in chat and the suggestion was to keep books for “real” books about TeX (i.e. those with an ISBN) and merge the other two tags. Any comments on this proposal?

Additional points to consider are the usage of documentation for (rare) questions concerning writing documentation and how the tutorials tag fits into the picture (my take: “documentation” is more of a reference document, while “tutorial” is something you read only once).

Answer 1

books ⇒ needs ISBN sounds good.

I don't know how the tags have been handled so far, but here's how I understand the three:

Documentation is about how the thing works, is typically written by the author or someone greatly involved with the project, and typically includes the source code.

A manual tells the user how to use the thing and can be used as a quick reference. Often structured closely along the structure of the thing. The hyperref manual is a pure manual without documentation.

A tutorial can be considered a sub-species of a manual, more educationally written and process-oriented, typically longer than a manual; it takes the user by the hand and leads them through the process of learning how to do something or use the thing. It might be about several topics, like The Not So Short Introduction to LaTeX2e.

These three things are not clear-cut, a lot of "documentation" on CTAN starts out with a manual. A "book" could be any of the three and very likely a mixture.

Furthermore, I suggest the introduction of documentation-writing, parallel to package-writing and documentclass-writing.

Answer 2

I vote for making manuals a synonym of documentation. I also agree with Caramdir's definition of tutorials. With regard to questions about writing documentation: They should be tagged as package-writing resp. documentclass-writing.

Answer 3

I agree with these suggestions.

• Let's keep books: I assume people browsing this tag look for real books, not for any possibly electronic documentation, merging would make it difficult.

• Let's merge manuals and documentation with the latter as the main tag. They are really similar, separate tags would mean looking for documentation being harder - and I like people who are interested in documentation.

• Also tutorials can remain separate, as it's a special kind of documentation, usually for beginners, let's support that.

Regarding writing documentation : I guess many such questions can be tagged more specifically. I mean, most here is about writing ... For special design we have book-design which could match sometimes: there are great examples of documentation designed like beautiful books. So, if ever needed, somebody could invent the tag documentation-writing or documentation-design to distinguish it.

Answer 4

I used {documentation} for my questions about documenting own packages (e.g. problems with docstrip, ltxdoc, …). May I misunderstood the tag but should’˝s there be a tag for this.