14

tl;dr

Documentation would fill a better niche and be generally more useful if we focused less on specific languages, and more on specific libraries. The largest examples of documentation that we have are centered around languages, of which there is already an abundance of elsewhere.

We as knowledgeable software experts should focus our efforts in Documentation to libraries used in these languages, and not the languages directly, to be decided by the people primarily involved in these languages.

Given that we're tearing down how Documentation works now, this would be a golden opportunity to address this issue.


I'm a bit over Documentation right now. To put it a gentler way, the way I want to contribute to it right now (doing more janitorial tasks and keeping silly requests at bay) isn't all that recognized. Worse, what I want to use it for isn't possible.

When it launched, I was enthused at what it could bring and what promise it held; it could bridge the gap between terrible documentation and very knowledgeable domain experts to really make something awesome.

However...

I'm starting to grow weary of seeing topics that cover really basic stuff. Like, easily Googleable stuff. We're getting a lot of noise here in stuff that's easy to search for, and not a lot of signal in the more complicated things. Why do I need the (n+1)th article on how to manipulate arrays?

We're not getting experts talking about the libraries that we deal with [on a constant basis] filling in the gaps behind different approaches of Spring Bean configuration; we're getting folks adding another coat of paint to the bike shed, and I admit I'm very guilty of this too.

I've been thinking on this since the whole brouhaha behind the reputation issue came about, and the primary thing that struck out to me was that it was the more popular and venerable languages that existed were the ones that gained more attention and more documentation.

I'm not convinced that this is a good thing anymore. Most every top language in Documentation has really decent documentation around it (I'm looking square at Java; those who haven't heard of the Java Trails haven't looked very well), and it feels like we're just regurgitating that information here.

So, my proposal is to remove language documentation from Documentation, should the community permit it to happen.

I'm not going to deny that smaller, lesser known languages like D could benefit from a system like this, but the larger and more influential languages like Java and C# don't really thrive in this system. They've already got a lot of documentation around them and adding the same information in another place on the Internet seems counter-intuitive.

How this would work:

  • Gold badge holders in a programming language (let's start right now with C, C++, C#, Java, JavaScript, Ruby, and Python) would be allowed to cast a vote on whether or not the documentation for their language is eligible for deletion.
  • If there are 10 votes in favor of deletion, the topics and the tag are hidden.
  • If the community decides to bring back the tag, Gold and Silver badge holders in that tag would be eligible to vote to bring it back.
  • If there are 30 votes in favor of restoration, it would be reinstated.
  • To mitigate flip-flopping, this sort of vote could only transpire once every so often; for instance, every six to nine months.
10
  • 4
    Not very different from SO. At well over twice as many articles as the largest collection of human knowledge, we can't exactly claim programmers have twice as many problems solved as the rest of humanity. Not everything is a keeper, community is powerless, Google sorts it out. If your motivation about other people's contribution start to flag then focus on what just you can do. Sep 10, 2016 at 21:59
  • 1
    @Hans, I failed to get that koan (it's late in our timezone), can you elaborate? Sep 10, 2016 at 22:01
  • 2
    What the heck is a koan? I'll look it up on Wikipedia. Sep 10, 2016 at 22:02
  • 2
    I agree with everything up to the voting to remove/re-add thing. Let's just remove them and be done with it. We'd get a lot more interesting examples, and insight into the languages, if we documented libraries instead. Then again, it would eventually fall into the same pattern: overeager users who don't really know how to write documentation or identify useful topics trying to contribute.
    – davidism
    Sep 10, 2016 at 22:29
  • 5
    I'm still waiting to see the holy grail of documentation: an example that improves the existing docs/resources and couldn't have been possible with a pull request to the actual thing. If those pearls are here, they're buried under a bunch of sand.
    – davidism
    Sep 10, 2016 at 22:33
  • @davidism: Personally I'd rather nuke them outright, but I'd rather provide the option to undo should we realize that we made a mistake... Not that I think deleting those would be a mistake, though.
    – Makoto
    Sep 10, 2016 at 23:33
  • 5
    @davidism: "couldn't have been possible with a pull request to the actual thing"... ignoring the fact that not every project has "pull requests", that was never the intent behind Docs.SO. It wasn't for things that couldn't have been done elsewhere; it's supposed to be for things that aren't being done elsewhere. Sep 11, 2016 at 6:04
  • @HansPassant " At well over twice as many articles as the largest collection of human knowledge" Wouldn't that mean we are the largest collection of human knowledge?
    – TylerH
    Sep 13, 2016 at 20:34
  • @davidism See: any language or library whose docs are written and decided upon by closed groups.
    – TylerH
    Sep 13, 2016 at 20:35
  • 1
    @TylerH I understand that part, what I meant was that it seems that all the focus is on things that aren't that: open source and popular.
    – davidism
    Sep 13, 2016 at 21:09

1 Answer 1

2

Your edit suggests this is good time to reconsider the idea because we are reconsidering the way the content is sturctured. I respectfully disagree. At the risk of putting my finger on the scales, it seems as if we are going to be moving away from strict silos organized by tag. Depending on how that works, it may require adjusting the proposal.

I get your point. There's no reason to suspect that crowd-sourced Documentation will work better than single-author documentation for extremely basic concepts. If Docs excels, it'll likely be on obscure topics that aren't already well represented on the internet. But notice that by deleting all topics in a tag and preventing any new topics, we'll never be able to know if that assumption is correct. Can we really know that no new documentation will ever be needed for, say, Ruby? I submit the only way to find out is to let programmers write the documentation they wish existed.

For the record, it's already possible for gold or silver badge holders to remove topics unilaterally. That means users who are active in a tag on Q&A have considerable power to shape Documentation. This proposal is more radical: block certain tags from getting Documentation at all. Specifically, you want to be able to block Documentation because there's too much existing stuff available. It feels like the Bizarro World version of Wikipedia's notability test. Instead of preventing topics because they are too niche, this proposal would prevent Documentation that's too common.

The top (and first) comment on the announcement was:

Unless you rework docs to be a service that provides product developers with a documentation platform that is smoother and easier to maintain than their own web sites or GitHub readmes or whatever, with a search function that yields more effective results than e.g. Google and is as or more convenient than typing search queries in your address bar, I can't see this ever adding value to the internet; it's a really fundamentally flawed premise no matter how many tweaks you try and make to it.

I think we can set our sights a bit higher than just improving upon READMEs and I'm not sure we need to beat Google with internal search, but it's still an ambitious mandate. If we succeed to accomplish that goal (and we aren't really close yet), it would be strange to say popular tags aren't able to benefit. And if we fail, there's not much need for this proposal at all.

3
  • A lot of the requests I see for new documentation coming through in Java (the only tag I'm watching right now) are for libraries instead of language fundamentals. A lot of the active requests right now in Java are for API usages which go beyond the basics. However, the majority of Java is full of easily-found information. This is where I see the need for documentation; things which aren't well-covered or easy to find on the Internet. By allowing simple topics to exist on Documentation, we run the risk of curating another bikeshed when the nuclear plant desperately needs new cement.
    – Makoto
    Jun 4, 2017 at 4:57
  • 1
    I really don't want to come across as too hyperbolic, so I'll rephrase. In my opinion, there's more value with the community spending time (better) documenting frameworks or libraries which go off the beaten path. Languages which lack this documentation could be supported under this, should their community here deem it valuable enough. Languages which have an abundance of this could eschew this system in favor of what exists, and leave our resources free to focus on the other parts which are sorely lacking in docs.
    – Makoto
    Jun 4, 2017 at 4:59
  • "If Docs excels, it'll likely be on obscure topics that aren't already well represented on the internet." Okay, but looking at what we have so far, users are duplicating e.g. the Java Tutorials, not writing about obscure Java topics. I think that's partially due to poor communication about the purpose of Docs (starting with the name itself) and partially due to rep incentives for editing popular things, not an insoluble problem. But I don't know, maybe you're already working on directing users to the things that actually need documenting as part of the redesign. Jun 4, 2017 at 5:06

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