74

Can a developer of an open-source library available to the general public choose to put their own documentation on Stack Overflow Documentation, provided it is formatted appropriately and not copied without attribution? If so, what guidelines should they follow?

  • Does it matter if the library is popular and widely used? If so, how much?
  • Should it have its own topic, or be part of another topic with a specific tag?
  • Does it matter if the documentation is duplicated elsewhere, or if similar documentation exists elsewhere? (Perhaps the same examples with different text.)

There may be other appropriate questions as well that I just haven't thought of. What are the rules on this, or are there any? Also, are they likely to change?

2
  • 23
    You have to propose the tag first. Could well be an obstacle right now if this is your own library, tends to be hard to find 4 other people that have SO answers in the tag. Why anybody would want to have to maintain multiple sources of documentation when they update their library is a mystery to me. Aug 2, 2016 at 14:41
  • 1
    @HansPassant I don't know that they would. As I said in response to Nicol Bolas's answer below, there's hardly any use repeating or copying existing documentation here. You'd have to post separate, working examples in an acceptable format. As for updating it with versioning changes, well... that's a general Docs.SO problem. Aug 2, 2016 at 15:15

4 Answers 4

44

Does it matter if the library is popular and widely used? If so, how much?

This matters in a roundabout way. The topic/tag for the library must exist and be committed to by 5 users. This requires having enough of a tag presence on SO main to have enough users who qualify even to create the SO Docs tag. So your library must have a corresponding tag with appreciable traffic on SO main for it to be relevant to SO Docs.


Should it have its own topic, or be part of another topic with a specific tag?

It should have its own tag. Then within that tag it can have any number of useful topics/examples.


Does it matter if the documentation is duplicated elsewhere, or if similar documentation exists elsewhere? (Perhaps the same examples with different text.)

Make sure you don't fragment the documentation between SO Docs and wherever else the documentation lives. From the revised Documentation overview (emphasis mine),

“Bad” fragmentation is where you now have to check more places to get the same assistance as before. If, say, Oracle were to cut the Java documentation in half and put one half on a different domain in a different style and format that would be bad fragmentation. Similarly, if Documentation just made it so you now had to check MSDN and Stack Overflow for the same quality information you used to get just from MSDN that would be bad fragmentation.

Make sure that whatever you do decide to post on SO Docs is enough to be a one-stop-shop for the most common cases of your library. Certainly there can be some overlap between SO Docs and (for example) a tutorial project provided in the API documentation. But SO Docs must be able to stand on its own in a helpful way without relying on link hopping to another site.

1
  • 3
    Thanks for touching each point individually. Aug 2, 2016 at 15:12
19

provided it is formatted appropriately

You seem to say this as though it were some kind of trivial matter. As though you could just use a "convert to Markdown" tool and then upload it.

That's not how this works.

Docs.SO is example-focused documentation. It's not "here's 100 lines about what the function does, now here's a 10-line example showing a trivial use of it." It's the exact opposite of that.

Docs.SO is not a reference manual. And most open source documentation is formatted and written as reference documentation.

Converting from one style to another is not a matter of using Markdown. You have to write a lot of code examples. You have to re-conceive your entire view of your documentation to make it work. It has to be completely rewritten, with a focus on code examples and not comprehensiveness.

Reference documentation is not something that Docs.SO does well. And projects still need that sort of stuff.

So regardless of attribution, simply copying-and-pasting to Docs.SO is highly unlikely to work out well.

5
  • 1
    I agree and I wouldn't want anyone to just copy and paste their docs. I only put that in the question so we could avoid this type of discussion. Obviously I wouldn't want a tool that just took whatever I put on ReadTheDocs and dumped it here with no changes -- that doesn't fit with Docs.SO. Same in reverse: doesn't fit with ReadTheDocs. I just want a canonical answer to what would happen if someone who understood and correctly used Docs.SO wanted to take the initiative and add examples for something they wrote. Aug 2, 2016 at 15:12
  • @Two-BitAlchemist: "I just want a canonical answer to what would happen if someone who understood and correctly used Docs.SO wanted to take the initiative and add examples for something they wrote." Why would we care who it was who wrote a bunch of Docs.SO examples? We don't forbid users from answering questions about the software that they wrote; indeed, we kinda encourage that. Aug 2, 2016 at 15:14
  • 4
    Kind of... but we do have prohibitions on undisclosed affilliations, so it would be nice to know if those apply to Docs. Additionally, the tag popularity requirements explained above are relevant. You couldn't just decide, "Hey, instead of <existing docs host> I want to use Docs.SO" for everything, at least not if you don't already have an existing and somewhat useful tag on SO. Aug 2, 2016 at 15:18
  • 2
    @Two-BitAlchemist "what would happen if someone who understood and correctly used Docs.SO wanted to take the initiative and add examples for something they wrote" -- you were asking for documenting your library. From what we've seen so far, using SOD correctly and documenting your library correctly don't mix. You can exemplify the use of your library in many simple ways, and SOD is the right place, and indeed nobody cares who the author is. I mean, you don't even need any rep or tag score for contributing to Docs (do you?). Aug 3, 2016 at 0:19
  • 2
    @AndrasDeak I feel like you and some others are answering this like it's a Stack Overflow question, rather than a Meta Stack Overflow question. I'm not asking about whether it's good practice to document using Docs. SO, exclusively or otherwise. I'm asking about community rules and preferences around using the tool if you are the author of the package in question. In Q&A, the rules are slightly different; I want to clarify the same with regards to Docs. That is all. Aug 3, 2016 at 1:08
4

I cannot see why not.

The problem is that the tag needs to exist on the Stack Overflow side, and each person that "commits" to write docs for that tag needs a certain number of rep within that tag.

As long as all of those things are complete -- I do not see any issue with it :-)

6
  • 10
    The tag itself also has to meet certain popularity restrictions at present (number of questions, not sure what else) and needs to have had a question asked in it within the last three days. I have a library that satisfied the former, but not the latter, and couldn't even suggest it as a topic as a result.
    – Brad Larson Mod
    Aug 2, 2016 at 14:49
  • 1
    @BradLarson: There are ways we can fix that. :) Aug 2, 2016 at 15:02
  • @RobertHarvey: Do we really want to turn Docs.SO into every open source project's dumping ground? Aug 2, 2016 at 15:03
  • 10
    @NicolBolas: Not every one. Just Brad's. Aug 2, 2016 at 15:04
  • 8
    @NicolBolas - To be honest, as a moderator I just wanted to become familiar with how Documentation works so I'd know how to moderate it. I have a bunch of code examples for specific use cases that I thought would clutter up the main project documentation and are currently residing in sample applications. Seemed like a good case to try and see if Documentation works for this.
    – Brad Larson Mod
    Aug 2, 2016 at 15:09
  • 3
    I don't even know what the complaint is there. "Every open source project's dumping ground" -- you could argue that's what StackOverflow is for questions. So what? If a whole bunch of open source projects decided to contribute Docs examples, how is that different from a bunch of random SO users doing the same? If you didn't want to see a project, then don't browse their tag. Aug 3, 2016 at 1:23
4

Docs.SO isn't really a complete documentation tool. It's more akin to Recipes and Examples, which are very useful, but aren't sufficient for a well-documented project.

I would recommend reading this article on how to write good documentation. There are lots of tools and websites available for writing documentation. I particularly like sphinx and readthedocs.org, but there are many others.

Having examples and tutorials on Docs.SO will definitely help users of your project, but it's not a good substitute for good, complete documentation.

2
  • 2
    As I commented above, this is a question on Meta Stack Overflow, not Stack Overflow. I don't want to know about whether or not it's good practice to document on Docs.SO, and I didn't say anything about documenting exclusively on Docs.SO. Your answer doesn't even touch on community rules. Aug 3, 2016 at 1:09
  • 1
    PS - I do use sphinx and ReadThe Docs. I have not used Docs.SO at all, to date. Aug 3, 2016 at 1:12

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