8

Python's documentation has a topic "Meta: Documentation Guidelines". Looking at its history, I see that it was created on April 7th with a pinned example:

These are just proposals not recommendations. Feel free to edit anything here if you disagree or have something else to mention.

Eventually this could be included or linked in the Hello World-topic.

At that time, another example was also added about how to include the outputs to examples. It was edited a couple of times but basically the recommendation was to put outputs in comments. For example,

x = 7
x
# Out: 7

One of my examples was edited citing this recommendation. It made sense to me so I decided to edit my other examples as well. I wanted to link that example but I saw that it was deleted.

It had 5 contributors and 8 upvotes before deletion and got deleted by 1 suggestion (as a result of an improvement request) and 1 approval (it had also 1 rejection).

Can we treat this topic like Meta where we upvote and downvote suggestions? If so, should we add the example again? Or is it too early to have rule-looking guidelines? Should these be discussed somewhere else?

Update: The topic got deleted.

1
  • 5
    This points to a broader problem: there's no place for editors to discuss what Docs should look like. (Compare most wikis' talk/discussion pages.) Commented Jul 23, 2016 at 15:07

1 Answer 1

2

I'm answering the more general question (not specific to Python):

"Or is it too early to have rule-looking guidelines?"

Beta is the perfect time to start talking about what Docs in a tag should look like. If a tag's community has some tentative guidelines, let's write them down so we can coordinate how we contribute to Docs; discuss it; and update the guidelines over time.

Maybe we will find that, in light of how we want to use Docs for a particular tag, some Docs features ought to be added or overhauled. Better to get to that point during beta than to wait.

Guidelines vs rules

We can have a guideline like

Handle x however you like, but keep in mind y and z.

This is the essentially the opposite of a rule. It offers some guidance to editors and sends a message to reviewers that "you're doing x wrong" is not a good reason to reject a contribution to Docs.

That's the stance taken in both the and guidelines for displaying output, like "Hey, here are some options for distinguishing between input and output. Please think about it and pick one."

Where to put such meta guidelines?

Oh, I don't know, maybe on Meta? They don't belong as examples in Docs, but until we have a better place for them, I think they should not be deleted simply for being meta. We may never get a better place for them... as seems to be the case for tag-specific MCVE guidelines.