Since there are many questions that ask what you commit to when you commit to a Documentation tag, it seems that “committing” isn’t the best description for what’s happening. Instead, I think there should be a proposal post. By default, it could look like this:
Let’s create documentation for Friendly Name.
Below, it should say something like this:
Once this proposal gets 5 votes, documentation for Friendly Name will be opened up for documentation.
If you don’t have the requirements to vote, this will also be shown:
To vote, you must have:
- 150 or more reputation on Stack Overflow
- 1 or more positively scored answers on questions tagged tag-name
If you meet the requirements, you can edit, vote, and comment on the post. There should be the edit, flagfor spam/unnecessary tags (I.E. [arrays] etc.), and dupefor setting the documentation to another tag (i.e. [python-3.x] → [python])
The box on the tag pages should show a snippet of the description.
So, here’s what I’m proposing for the “commit” page:
Let’s create documentation for Friendly name! (not editable)
v The community proposal goes here.
/_\ Some things that go here:
* What’s getting documented?
3 * Why should we document this?
* Anything else about the tag
\ /
^
share edit flag
This sounds great! — A user sometime
-1: This is a bad idea. Because reasons reasons. — Another user sometime later
add a comment
These users have upvoted:
User 1 User 2 User 3 |(empty box)| |(empty box)|
Here’s what the flag dialog could look like:
I am flagging to report this proposal as:
spam
This proposal exists only to promote a product or service, does not disclose the author's affiliation.rude or abusive
A reasonable person would find this proposal inappropriate for respectful discourse.
too narrow
This content would be better as a topic or an example, not a tag.too broad
This content covers a language feature that is implemented in very different ways in different languages (like functions or arrays)a duplicate…
This content is already documented in another tag or topic.in need of moderator intervention A problem not listed above that requires action by a moderator. Be specific and detailed!
The first two and the last one apply to the content of the proposal itself, the others apply to what would be documented.
Too broad would apply to such tags as array and function that are better candidates for being documented in each language tag.
Too narrow would apply to topics like swift-dictionary that shouldn’t stand alone.
Duplicate would apply to tags like swift-3 which should redirect to swift.
If you went to the docs for swift-3, a message should show up after you redirect to swift:
You’ve been redirected to the Swift Language documentation because the swift-3 documentation was closed as a duplicate of this one. You can still view the original proposal if you want it to be considered for reopening.