I'm part of the team developing the JSON Schema specification. I was going to suggest to some of the team that we document some aspects of the specification on the Stack Overflow documentation site, however I'm not able to contribute in any way.

This is despite the information about Stack Overflow documentation saying anyone can contribute.

I appreciate there needs to be some gatekeeping, however I feel this is a somewhat unnecessary blocker.

I feel it's preferable that the JSON Schema team add documentation on the Stack Overflow site rather than the JSON Schema site, but I'm unable to actually allow people to do so. It feels like a barrier to entry in this instance. (Maybe there could be some way for a user to request an admin override on the requirements?)

Thoughts are welcome.

  • 3
    You dont have any answer in jsonschema tag and it should be upvoted too to commit to proposal try to answer unanswered question in that tag and you are good to go. Dec 21 '16 at 12:14
  • 10
    I feel it's preferable that the JSON Schema team add documentation on the SO site rather than the JSON Schema site - Why do you feel that way? (It's a serious question given all the hand-wringing about Documentation elsewhere. Do you think SO Docs fits your needs?) Dec 21 '16 at 18:38
  • 4
    I second @JeffreyBosboom's question. What about Documentation makes it a better fit for you than your own website? This has been to topic of much discussion as of late, and it would be nice to hear a different side of the story.
    – user4639281
    Dec 22 '16 at 1:11
  • 9
    Sure, got no problem explaining. I feel the team (inc myself) want to create documentation in collaboration with the community. There's some discussion about what should and shouldn't go on the website internally. I also feel the documentation on SO will be faster to be updated, get more reviews (to check for issues), and be easier to maintain. Updates to the website is currently a really slow process... much slower than the speed of the specification development. Dec 22 '16 at 10:06
  • 1
    I think this would be the single best use of Documentation I've read about in some months now. Thank you very much for trying to centralize your contributions. Dec 23 '16 at 23:15
  • Thanks @FélixGagnon-Grenier - The story about how the current development team took over the work / project of JSON Schema is a bit interesting too. No one could regain control of the the Github organisation, so we had to start a new one, and direct people too it. The domain is somewhat tricky also... we still don't know who controls it, but anyone can pay for it... strange system! Dec 26 '16 at 8:02
  • I read your question and it immediately raised another question: Why can't I commit to a version-tagged proposal?
    – Matt
    Jan 27 '17 at 9:39

Everyone can contribute to documentation that exists.

If documentation does not exist for a particular topic, it has to be created first, and we want to make sure that it is worth creating. That includes concerns about triviality, topicality, and whether there are enough willing contributors to ensure it won't be a wasteland. (It should include concerns about the prior existence of documentation for other redundant tags, but it doesn't.)

It does seem odd to me that you have knowledge and a desire to share it, yet have not answered any questions about this topic. A single upvoted answer on a question with the tag would be enough to allow you to commit to documenting it. I really don't think this is setting the bar too high.

  • 8
    Re: your last paragraph. I think the main concern is that he wants the rest of the json schema developers to also contribute to Docs, but he probably doesn't want to require that they all go answer questions first. The merits of doing so are debatable, but I think it warrants discussion.
    – user4639281
    Dec 22 '16 at 1:14
  • 8
    I can understand your aguments here and they do feel valid in a lot of cases. Currently the people maintianing JSON Schema are very few, with very limited time. Previously people were directed to a google group for questions, but I fixed that to direct people to SO. We hardly have time to keep up with Github issues, and we aren't strategically devoting time to SO questions, and maybe we should. Carving the time is a huge problem for JSON Schema and those maintaining it. Especially when such huge companies (AWS, Google etc) and API definitions services (Swagger, RAML) are using it. Dec 22 '16 at 10:13
  • Yes, @TinyGiant is correct. I'm not even sure everyone on the team HAS an SO account (Yet). Dec 22 '16 at 10:24

I really don't think this is setting the bar too high.

This quote from another answer pins down the crucial question, doesn't it. Is a single upvoted answer in the tag asked for too much or not?

It may depend on the tag. There are currently 863 questions tagged and with on average 0-2 new questions everyday and 270 unanswered questions. So, it's not a high traffic tag but still it should give some opportunity to get to get the required minimal single upvoted answer.

On the other hand, what exactly is the difference between a single upvoted answer and no answer at all? What is the concern we have here (spammers or low knowledge)? Is it valid?

We could just try it out. Let everyone contribute and if the experience is bad, go back.

  • 4
    The issue here is not mere contribution, since anyone can contribute to existing docs. The issue is committing to create a new topic. That already has a significantly higher bar, since 5 users must commit in order to have it be created. I gave various reasons why that is important in my answer. And simply having it be 5 random users leaves it too open to abuse. Requiring a single upvoted answer in a relevant tag helps to ensure that you are a real person and actually plan to contribute. It is not perfect, of course, but there's no check on committing like there are reviews for submissions.
    – Cody Gray Mod
    Dec 23 '16 at 13:57

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