TensorFlow sounds cool. And I'm an experienced programmer with a highly relevant background, so I'm working through the "Quick Start" guides. But I'm going very slowly, because I'm finding the documentation to be patchy—abbreviations and terms not defined, guidance to finding code for examples not provided, "obvious" things left unexplained. Essentially it feels like death via a thousand paper cuts, none of which is a particularly big deal in and of itself.

I want to suggest improvements to the documentation—highlight what's not clear. There's no obvious way to do it. Instead, for support, TensorFlow suggests two options: try the GitHub issue tracker (whose "New Issue" button tells me to go to Stack OverFlow) or come to Stack Overflow directly. I can't imagine how a thousand small questions in a hundred different voices are going to help TensorFlow improve its documentation. Chances are it will pollute Stack Overflow with low quality questions instead.

Should the likes of TensorFlow be encouraged to set up their own Q&A/feedback forums rather than relying on Stack Overflow?

Or perhaps better: could someone come up with a way to highlight web content online, and provide an option to state "this was not clear to me" and provide constructive feedback precisely where it would help?

  • 198
    Maybe Stack Overflow could start a documentation project? – Stephen Rauch Jan 24 '18 at 2:24
  • 12
    Why do the questions have to be low quality? If this is something that you're running into, and other people are likely to run into, why don't you ask a high quality question, get a good answer, and then the rest of those who would be stumped in the same situation can breeze on through thanks to your efforts? – user4639281 Jan 24 '18 at 2:38
  • 5
    The answer to your title is an unequivocal "hell yes". This is a core facet of the mission. – Josh Caswell Jan 24 '18 at 2:38
  • See also meta.stackoverflow.com/q/356660/1038015 – Robert Longson Jan 24 '18 at 2:39
  • 8
    @TinyGiant Example of inevitably low quality question: "what does DNN stand for?" If you take it out of the context of the documentation, you get all sorts of angry downvotes and a closed question. Eventually you understand that it means "deep neural network" but that it seems to be a misnomer because they're introducing it first in a shallow sense that conflicts with other understanding/terminology in common use outside Google. It all adds heat, not light, and should be explained and/or fixed in the documentation itself, not elsewhere. – omatai Jan 24 '18 at 2:45
  • 5
    Looks like they actually do expect you to report issues with their documentation via GitHub: github.com/tensorflow/tensorflow/… – BSMP Jan 24 '18 at 3:04
  • @BSMP If you click the "New Issue" button, you would read a message that strongly suggested otherwise. I would suggest 9 out of 10 people would immediately go to StackOverflow as instructed. – omatai Jan 24 '18 at 3:20
  • 1
    @omatai we have a terminology tag for a reason. Terminology questions are not inherently off-topic so long as they are narrowly scoped and well-defined. Such questions can often be immensely useful for those who come up with the same description of a thing without knowing the name of the thing, or when they read an acronym that they just cannot find the definition of anywhere else. There's nothing inherently low quality about short / beginner questions (beginner being relative to the technology, not SO), so long as they are narrowly scoped and well-defined. – user4639281 Jan 24 '18 at 3:56
  • 4
    @StephenRauch Actually, we did already – Filnor Jan 24 '18 at 10:25
  • 24
    Not to split hairs, but it sounds like they're using Stack Overflow as a substitute for good documentation, which it isn't. It's roughly equivalent to patchy documentation, so it is indeed a fair substitute for that. – Bill the Lizard Jan 24 '18 at 13:30
  • 4
    You should probably open an issue asking for them to make it clearer that you can open an issue for documentation problems. – BSMP Jan 24 '18 at 15:28
  • 8
    They should fix their damned documentation :/ Writing patchy documentation is bad to begin with, not improving it because Stack Overflow exists is a sin and a reason why I would not have any faith in the quality of the product. – Gimby Jan 25 '18 at 10:55
  • 17
    @chade_ Did you notice a loud "whoosh" when you posted your comment. :) – rmaddy Jan 25 '18 at 23:27
  • Eithere tell the Tensorflow developers to produce good documentation, make it yourself or ignore Tensorflow in the future. StackOverflow cannot replace documentation. – Trilarion Jan 26 '18 at 19:45
  • The new issue text seems rather clear. It simply says if you have a question, go to stackoverflow.The issues tab is for issues, not implementation problems or help. To me a request or suggestion to improve the docs would seem valid there. – Kevin B Jan 26 '18 at 20:28

Funny you mention this.

Up until recently, Stack Overflow had a dedicated documentation project, which was sunset in mid-2017. While it's a shame that the project ultimately collapsed on itself, the need is still there; hopefully it can be revisited with a focus on libraries instead of languages. #justdocumentationcomplaints

To answer your question directly..."reasonable" is a very strong word. It has served as patchy documentation since its practical inception, and many developers understand innately that this is the best place to find good and accurate information about the library you're using. Is it reasonable? Well, no, given that not every library is going to be covered, nor is every circumstance going to be concisely documented by the community.

I believe you have some fortune in that you can actually file an issue on GitHub in regards to unclear or obtuse TensorFlow documentation. The only value that Stack Overflow could possibly provide in this circumstance is if the maintainers didn't provide this opportunity.

I'll spare you my opinion/diatribe on what the site could've done better to actually have working documentation, and instead let you read through the three posts I've linked to for some context.

  • 2
    As noted to @BSMP above, if you click the "New Issue" button on the GitHub link you provide (which I visited before posting, but was scared off by), you would read a message that strongly suggested they are not open to such contributions. I would suggest 9 out of 10 new people would immediately go to StackOverflow as instructed. – omatai Jan 24 '18 at 3:27
  • 5
    @omatai: If there's an actual bug with their documentation (and I would consider documentation being unclear as an actual bug), what's the issue? The worst they can do is decline your bug report and ask you to say something on Stack Overflow. (Then, you can link them to this Meta question instead.) – Makoto Jan 24 '18 at 3:28
  • 1
    "[...] While it's a shame that the project ultimately collapsed on itself " no, it did not. Your so called "project" was fine, it was just killed by spoiled community that believes no change is better then good change. if Progress.Try() then new Exception("It's bad.") endif The sooner we stop lying to ourselves and end with all that mendacity, the better. – Skipper Jan 24 '18 at 10:48
  • 4
    "it's a shame that the project ultimately collapsed … hopefully it can be revisited" — no, not that again, please. We should bury that even deeper, just not deep enough to completely forget about it (or else someone may accidentally try to implement that again). – user1643723 Jan 25 '18 at 7:49
  • 2
    Seriously +1 in regards to the documentation project "hopefully it can be revisited with a focus on libraries instead of languages"! – Blizzardengle Jan 25 '18 at 18:49

https://github.com/tensorflow/tensorflow/issues/new says “Please go to Stack Overflow for help and support” but reporting cases of deficiencies/ambiguities/missing information in the TensorFlow docs isn’t “help and support” — it’d instead be an issue that they need to consider fixing.

So, seems like the right thing is to file issues against the docs. That’s the way to fix/improve them.

People just asking questions on Stack Overflow about those kinds of cases does nothing to help the TensorFlow maintainers improve those docs.

Case in point: Above there’s mention of the specific case of the docs using the term DNN but not ever defining what is meant by it — and further “they're introducing it first in a shallow sense that conflicts with other understanding/terminology in common use outside Google”.

It seems like documentation that has deficiencies like that is buggy, not just “patchy”. That looks like a case of something being ambiguous to the point it risks misunderstandings.

And in cases where you have worked through the docs to the point you’ve managed to discern what they actually mean by something, you could open a pull request against the doc sources, which seem to be at https://github.com/tensorflow/tensorflow/tree/master/tensorflow/docs_src.

I think the sad truth is that most projects have really bad docs. And in some (many) cases the docs aren’t maintained in a way that allows people to contribute to improving them. So it seems like cases such as the TensorFlow case are a good opportunity.

To look at it from another perspective, contributing questions and answers to Stack Overflow is a way to help others in the future who run into the same questions and problems. Contributing issue reports and pull requests to the TensorFlow would have the same purpose — and arguably, for the reasons stated above, it seems like for this case it’s be a better way to help others in the future.

  • 6
    Part of the issue, to me at least, is that English is not a language that spits out compiler errors when you use it differently from one region to another. Where I come from, only software can have bugs and features - documentation is a different thing. So I have requested they make it clear that documentation issues are valid issues to raise on GitHub. – omatai Jan 24 '18 at 20:45
  • 5
    You are far more diplomatic than I would be. I have no tolerance for tools or libraries that don’t provide good documentation. And Stack Overflow certainly is not a reasonable substitute—it’s a last resort, where people collectively reverse engineer the current behavior. – VGR Jan 25 '18 at 23:55
  • @vgr, I disagree, sort of. Good documentation is really hard. A primary problem is knowing what to document. The advantage of SO, is that the questions can help frame what information is missing from your documentation. I am not trying to excuse crappy documentation in general. I am just trying to say that using SO as a backstop to finding holes in your docs, seems like a reasonable thing to do. – Stephen Rauch Jan 26 '18 at 4:31

I arrive at this conversation after spending 5 days locked in a room with our software partner for our invoicing forms. 2 years and change after the go-live to Dynamics AX 2012 and we as a company are just now acquiring quality documentation on the software. The problem is widespread from where I sit, our users struggle with complex ERP processes and support staff struggle to support the user with quality processes and troubleshooting because we have a limited understanding of the systems ourselves. This stems from poor training and a lack of documentation. As a community, we have the opportunity to create a more complete user guide for the members and develop a support structure that is more universal, at least at a very basic level. I would love the opportunity to address these documentation issues as a community and begin the collaborative effort to close the gap between software and user.

  • Sorry but that's what we tried to do and it didn't work out. See links in accepted answer. – JonH Jan 26 '18 at 20:11

You must log in to answer this question.

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