10

At the moment we have three tags concerning documents about TeX: , and . The only one with a wiki is , 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 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 for (rare) questions concerning writing documentation and how the tag fits into the picture (my take: “documentation” is more of a reference document, while “tutorial” is something you read only once).

  • 2
    The ISBN requirement is maybe a bit restrictive if we want to allow ebooks: most have ISBNs, but the DOI system can be used with them instead. What if we say instead, "real books, which generally will have ISBNs", which is more guidance that policy stipulation? – Charles Stewart Sep 19 '11 at 13:53
5

⇒ 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 , parallel to and .

3

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

3

I agree with these suggestions.

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

  • Let's merge and 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 .

  • Also 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 which could match sometimes: there are great examples of documentation designed like beautiful books. So, if ever needed, somebody could invent the tag or to distinguish it.

  • 2
    The only issue that might arise by combining the manuals and documentation tags is that there are a number of issues related specifically to documenting source code in TeX (especially related to docstrip and friends) which really don't fit nicely into the manuals tag. This point is also made by doncherry. (I realise that that is helped by making manuals the synonym and not the main tag, but it's still something to consider IMO.) – Alan Munn Sep 18 '11 at 20:11
  • The merge is done – Joseph Wright Nov 1 '11 at 16:15
0

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.

  • You could retag your questions to {documentation-writing}. – Stefan Kottwitz Nov 28 '11 at 8:27

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .