67

The tag (currently 6.9k questions, 432 followers) seems to be a hangout for miscellaneous questions, many of them off-topic resource requests for links to outside documentation or documentation tools. The tag wiki consists of three links to resources about technical writing:

About

 

1. Does it describe the contents of the questions to which it is applied? Is it unambiguous?

No, the tag is used for:

  • resource requests for outside documentation (off-topic);
  • resource requests for documentation tools (off-topic);
  • assistance with writing general software documentation (potentially problematic, but not per se off-topic); and
  • questions about specific inline documentation practices or platforms, such as or .

2. Is the concept described even on-topic for the site?

Some of it is (, ), some of it isn't ("oh hai, i can has documentation for X system?").

3. Does the tag add any meaningful information to the post?

Possibly, but not a great deal.

  • Questions about specific documentation systems such as JSDoc can get by with just a tag for the documentation system.
  • Questions about general documentation practices tend to be too broad, primarily opinion-based, and/or off-topic and should be closed and deleted anyway.
  • Questions about writing, editing, or understanding inline documentation could be tagged with an tag instead, and questions about software manuals (to the extent that such are on-topic) could be tagged or similar.

4. Does it mean the same thing in all common contexts?

No, a question tagged and could be:

  • about specifically;
  • about inline documentation commenting practices in general as applied to Java;
  • a request for a link to Java documentation (off-topic);
  • a request for a tool recommendation for generating documentation based on Java code (off-topic); or
  • a request for help with writing, understanding, or editing a software manual for a Java program or API.

This has nothing to do with the deprecated Stack Overflow Documentation platform or its associated Meta tag .

13
  • 3
    Indeed, I've rarely seen a tag where the overview list already shows most questions are clearly OT. Commented Nov 28, 2017 at 12:57
  • "Is the concept described even on-topic for the site? Some of it is (jsdoc)" I didn't knew that jsdoc is a concept called documentation. Can we stick with concept being the just the literal meaning of the word, please?
    – Braiam
    Commented Nov 28, 2017 at 20:22
  • 3
    Don't most questions about documentation (e.g. UML, requirements documentation, etc.) belong on Software Engineering SE now? Commented Nov 28, 2017 at 20:38
  • 4
    @Braiam jsdoc is a kind of documentation. It is generally on-topic, but many other things that fall under the concept of documentation are not. Airplanes, airships, and baloons are kinds of vehicles, but we don't need a [vehicle] tag on Aviation.SE. Commented Nov 28, 2017 at 20:56
  • By "burn [document]", do you mean delete all of the tags, or delete the questions?
    – Cpp plus 1
    Commented Nov 28, 2017 at 22:22
  • "jsdoc is a kind of documentation", what that even mean? "JSDoc is a markup language used to annotate JavaScript source code files", jsdoc doesn't mean documentation.
    – Braiam
    Commented Nov 28, 2017 at 22:22
  • 6
    @Braiam "JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor." It produces documentation, thus it's not incorrect to describe it as "documentation". In fact, avoiding the use of the word "documentation" makes describing it less accurate. It's not just "a markup language", it's specifically used for the purpose of documentation.
    – user3702702
    Commented Nov 28, 2017 at 22:41
  • 2
    @Cppplus1 What typically happens is that we'll go through them and identify close-worthy questions. Most of those questions will be migrated or closed and deleted (although a few may be closed and re-tagged or historically locked). Stuff that doesn't deserve to be closed will be re-tagged. In general, we try not to remove valuable content as part of burninations Commented Nov 28, 2017 at 22:42
  • @Archmage "documentation ˌdɒkjʊmɛnˈteɪʃ(ə)n/ noun: documentation 1. material that provides official information or evidence or that serves as a record. 2. the process of classifying and annotating texts, photographs, etc." (Google) A tool that generates documentation is not documentation by itself, if it was, then pencil and paper are documentation because they are used to write them, same with computer, etc. Don't conflate a tool with its purpose.
    – Braiam
    Commented Nov 29, 2017 at 12:00
  • @Cppplus1 just delete the tag wiki, and remove the tag from all posts. See the burninate process for more info.
    – NH.
    Commented Nov 29, 2017 at 21:29
  • 1
    If only there was some place where we could answer all these documentation questions... maybe people could request a topic? just some bluesky thinking ... Commented Nov 30, 2017 at 7:52
  • 1
    @AshleyMedway Which ones? You can ask general questions about writing documentation on Software Engineering SE or Writers SE I think. In terms of asking for assistance locating documentation, it's off topic everywhere on Stack Exchange I think... maybe ask in chat? Commented Nov 30, 2017 at 13:52
  • inline-documentation tag mentioned in the post is currently at zero questions....
    – bad_coder
    Commented Oct 6, 2020 at 12:40

2 Answers 2

7

Cleanup complete!

As of 14:07 EST 7 Mar 2018 there are 1,877 open questions, from original 6.9K.

  • Tag wiki & excerpt re-written.

  • There are about 2K closed questions that are candidates for deletion, but today all the open tickets are on-topic.

  • It would still be feasible to burninate the tag as Robert suggested, as any remaining on-topic question could be tagged with the specific automated documentation system it's related to... However there are quite a few that are language-agnostic. A better alternative, IMHO, would be to synonymize to .

2
  • I've been tracking progress on cleaning up this tag here.
    – Mogsdad
    Commented Jan 9, 2018 at 20:51
  • This left one problem, the documentation-generation tag-wiki doesn't allow for retagging like the documentation tag-wiki. Even without a synonymize the documentation-generation should provisionally include an entry (mention) to allow retagging questions about generators where the input/output languages are the standards. It would also be good if this post had an explicit entry saying the same criteria is applied to both tags.
    – bad_coder
    Commented Oct 5, 2020 at 0:55
-6

It describes the on topic posts. For the off topic posts, the solution is to attempt to close them and/or edit them to remove the flag. If it's ambiguous for on topic posts, we should come up with unambiguous replacements first, then have an organized effort to replace the tag rather than just get rid of it.

8
  • 7
    Please elaborate. What on-topic posts? Please give some examples of posts which have a good usage of the tag in an on-topic question.
    – Adriaan
    Commented Nov 29, 2017 at 17:01
  • 1
    @Adriaan the question already described four classes of post that this tag is (supposedly) used on, two of which are off-topic and two of which are not.
    – Mark Amery
    Commented Nov 29, 2017 at 21:14
  • The jist, I think, is whether keeping the tag for the usages that are on-topic actually adds something useful to the associated questions without causing too many problems. Commented Nov 29, 2017 at 21:18
  • 1
    @MarkAmery, but the cited on-topic posts have other, relevant tags and the [documentation] tag offers to additional value. Adriaan is asking for examples of on-topic posts which don't fix that situation.
    – Waylan
    Commented Nov 29, 2017 at 21:19
  • 1
    @Waylan "the cited on-topic posts have other, relevant tags and the [documentation] tag offers to additional value" - sure, in the case of questions about stuff like [jsdoc], this seems likely to be true (and if it isn't, then the right solution is probably to add the more specific and useful tags, not to keep [documentation] around). Adriaan's comment (as I interpret it) had nothing to do with [documentation] being redundant, though; he's challenging the idea that any appropriately-tagged [documentation] posts are on-topic at all, when the OP already agreed that they are.
    – Mark Amery
    Commented Nov 29, 2017 at 21:23
  • 1
    @MarkAmery, so then provide those examples which are on-topic and [documentation] adds value/is not redundant.
    – Waylan
    Commented Nov 29, 2017 at 21:27
  • @Waylan What? I just explicitly agreed with you that such examples probably don't exist, and now you're asking me to show them to you?
    – Mark Amery
    Commented Nov 29, 2017 at 21:28
  • 1
    @MarkAmery, sorry. Apparently I either misunderstood you or Adriaan (or both). Warren makes an assertion that the tag should remain for the on-topic posts. I'm saying (and interpreted Adriaan as saying) that someone needs to provide some examples which are both on-topic and not redundant (because I (and presumably Adriaan) question their existence). Whether its the on-topic issue or redundancy issue that is not met is immaterial. Either one is enough to negate Warren's argument. You seem to be in disagreement with Adriaan, therefore my responses.
    – Waylan
    Commented Nov 29, 2017 at 22:24

You must log in to answer this question.

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