21

The Stack Overflow Documentation of [youtube-api] is, at this point, not very advanced, to say the least.

Obviously I can't speak for you, but I personally always try to consult the official documentation provided by the creator/maintainer of a service or product (that is, if I am confident that said entity is providing high-quality and most importantly up-to-date documentation, which is the case with Google in my opinion).

That makes me wonder if we really need separate documentation for the YouTube APIs on Stack Overflow, since virtually all of its possible contents are probably already covered by Google. They provide guides to getting you acquainted with the concept of the APIs, code samples for multiple programming languages and a complete reference for all API endpoints and their parameters, among other things.

I feel that documentation on Stack Overflow could not add any considerable value to the existing, official documentation and would instead lead to a fragmentation of information. That comes with the risk of the service being updated and the official docs along with it, with the Stack Overflow docs becoming obsolete when not updated accordingly.

I therefore propose to either close/discontinue Stack Overflow documentation for [youtube-api] or to only have it contain content that is not yet covered by the official documentation. Either way, I would refer users to Google Developers whenever possible.

I understand that the Documentation tour page justifies Documentation with 'prioritizing good examples', but again: I don't think it's necessary in this particular case since Google has already done a good job at that.

EDIT: I'd like to add that I would still be committed to helping this specific documentation become of use to Stack Overflow users, whatever the outcome of this discussion. All within my possibilities.


Amendment 1

I was asked in the comments whether I am advocating only keeping documentation for tags where an official documentation is either not present or insufficient.

I wasn't sure about this when I posted the original question. The intent was to collect other people's thoughts, primarily, of course with my own opinion being voiced as well. Considering the points brought up so far (especially that Stack Overflow Documentation should be regarded as a cookbook), I, personally, am now in favor of keeping Documentation for tags like [youtube-api].

My preference is to follow @Braiam's cookbook advice, while still trying to keep redundancy at a minimum. That means, focusing on very specific problems that are not already explained by Google (see this comment). This results in a follow-up question. The documentaion tour states:

Documentation is divided up by its subject matter, the library, language, framework, etc. that developers are using.

Therefore, how should documentation for [youtube-api] be structured (i.e. by subject matter, by language, etc.)?

PS: advice on how to proceed with this new matter (opening another question or continuing in this thread?) greatly appreciated!

(End of Amendment 1)


On a side note as someone who is kind of a regular at [youtube-api], I know for a fact that many questions with that tag can be solved by simply looking at the API reference. Because that's what I do when I answer those questions.


Interesting:

10
  • 25
    The thing is that Documentation.SO wasn't supposed to replace brick and mortal documentation from the developer, but being a cookbook... called documentation.
    – Braiam
    Apr 16, 2017 at 17:34
  • 5
    I agree, very narrow topic that don't have any potential for some great examples. I think we should approve the google-api tag and move the examples there under [youtube-api] topic. The same goes for google-maps and other google-XXXX-api's - Goup all under one tag
    – Alon Eitan
    Apr 16, 2017 at 18:09
  • 2
    @Braiam I recognize your argument. In that case, possible documentation examples could be: 'Get video information with PHP', '... with JavaScript', '... Ruby', 'Get channel information with the (PHP|JS|C|Ruby|...) client library', 'Upload a video with PHP' and so on, maybe categorized in topics for each task or each language. I can definitely see some use cases where a user wants to perform a very specific task (that maybe even has multiple steps to it) and finds help in such a cookbook (e.g., adding videos to a user's playlist in a random position automatically as soon as they watch them).
    – paolo
    Apr 16, 2017 at 18:29
  • 2
    One argument in favor of keeping the sections is that Google doesn't always update their examples to the latest versions of their libraries. I think the tags should be kept separate though (not combined into one Google tag). The reason being that tags are most valuable to people who are browsing questions in order to answer those related to their own expertise. Conceivably Google developers could be on here, looking for questions relating only to their department. Apr 16, 2017 at 21:32
  • 2
    Not sure it's a dupe, but it's highly related meta.stackoverflow.com/questions/344212/…
    – Machavity Mod
    Apr 16, 2017 at 23:15
  • Is the question is implying there should only be stack overflow documentation when the existing documentation sucks? If so, that'd certainly be a shift in the vision of documentation?
    – Goose
    Apr 17, 2017 at 17:58
  • @Goose I have amended the question, hopefully I could shed some light.
    – paolo
    Apr 17, 2017 at 19:13
  • 4
    @Goose That is the stated vision of Documentation, though. "What should be documented? Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow." Given that we award rep for most any "contribution", it's not surprising that you, er, see the vision to be something else. Apr 17, 2017 at 20:20
  • 1
    @JeffreyBosboom ah my bad, I didn't know that. I gotta say though, looks like documentation is currently being made for every topic, most likely because the rep system doesn't reward someone for not making a documentation topic just because the existing documentation is great.
    – Goose
    Apr 17, 2017 at 20:26
  • 3
    Replace "youtube-api" with literally anything that is already documented elsewhere, and the question still makes sense.
    – asmeurer
    Apr 17, 2017 at 23:42

1 Answer 1

10

Examples based on real world questions can be useful in addition to documentation written by the API developers before the API got any real world usage.

However most of the “documentation project” on Stack Overflow just seems to be people writing documentation for the sake of getting rep, rather than creating an example in response to an issue they have seen in lots of StackOverflow questions.

So I think the Stack Overflow Documentation of [youtube-api] is of about as much benefit as the rest of the Stack Overflow Documentation, in that it could be a great set of example based on real world questions…..

0

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