Skip to main content
Copy edited (e.g. ref. <https://en.wiktionary.org/wiki/supplement#Verb>). Expansion.
Source Link
Peter Mortensen
  • 31.2k
  • 4
  • 24
  • 14

An issue I see with this is that while Stack Overflow Docs may become the de-facto source for documentation, it can't be the authoritative source if official documentation exists. InIn some cases, like actual standards documents, the documentation is correct by definition: if ISO publishes a new Technical Corrigendum to the C standard that contradicts what's written on SOStack Overflow, the SO docsStack Overflow documentation instantly become incorrect, no matter how well written.

Even if the official documentation is considered non-normative, you still potentially can end up with situations where SOStack Overflow documents the way a system actually works, but contradicts the official docsdocumentation. ItIt could well be that the official docs aredocumentation is still correct and there's a bug in the system. TheThe best course of action in such cases is to contact the author and inform them of the inconsistency so they can deal with it, not to pick one of the inconsistent options and document that. If SOIf Stack Overflow becomes the de-facto source for docsdocumentation, it may create situations in which the bug can't be removed without confusing everyone who uses the SOStack Overflow documentation.

Normal Stack Overflow works fine, since we can answer questions about a specific scenario that isn't mentioned in the docsdocumentation, and then reference the document (or set of documents) that relate to the problem. It's more or less explicit that the answers are subordinate to the formal documentation.

That said, I do think there is room here to supplimentsupplement the official documentation in a way that the existing Stack Overflow does not. IfIf Stack Overflow Docs concentrates on examples of common uses (carefully edited so as to not become exhaustive to the point of uselessness), this would help address a weakness of much of the existing documentation.

Several others have mentioned tutorials; I think that would be excellent, especially if said tutorials referenced the relevant parts of the official documentation in each section. SuchSuch references, coupled with the existing voting and commenting system, could help keep the tutorials and examples listed here at a higher level of accuracy than the ones that are basically "This is what I was told when I first learned how to use it, and I never questioned it".

So in summary, I think that creating a set of well-written, reliably-accurate examples and tutorials would greatly benefit the overaloverall level of online documentation without running into the fragmentation issues that duplicating the documentation itself, since there's a clear division of purpose: Stack Overflow Docs is an introduction; the official docs aredocumentation is the reference manual.

An issue I see with this is that while Stack Overflow Docs may become the de-facto source for documentation, it can't be the authoritative source if official documentation exists. In some cases, like actual standards documents, the documentation is correct by definition: if ISO publishes a new Technical Corrigendum to the C standard that contradicts what's written on SO, the SO docs instantly become incorrect, no matter how well written.

Even if the official documentation is considered non-normative, you still potentially can end up with situations where SO documents the way a system actually works but contradicts the official docs. It could well be that the official docs are still correct and there's a bug in the system. The best course of action in such cases is to contact the author and inform them of the inconsistency so they can deal with it, not to pick one of the inconsistent options and document that. If SO becomes the de-facto source for docs, it may create situations in which the bug can't be removed without confusing everyone who uses the SO documentation.

Normal Stack Overflow works fine, since we can answer questions about a specific scenario that isn't mentioned in the docs, and then reference the document (or set of documents) that relate to the problem. It's more or less explicit that the answers are subordinate to the formal documentation.

That said, I do think there is room here to suppliment the official documentation in a way that the existing Stack Overflow does not. If Stack Overflow Docs concentrates on examples of common uses (carefully edited so as to not become exhaustive to the point of uselessness), this would help address a weakness of much of the existing documentation.

Several others have mentioned tutorials; I think that would be excellent, especially if said tutorials referenced the relevant parts of the official documentation in each section. Such references, coupled with the existing voting and commenting system, could help keep the tutorials and examples listed here at a higher level of accuracy than the ones that are basically "This is what I was told when I first learned how to use it, and I never questioned it".

So in summary, I think that creating a set of well-written, reliably-accurate examples and tutorials would greatly benefit the overal level of online documentation without running into the fragmentation issues that duplicating the documentation itself, since there's a clear division of purpose: Stack Overflow Docs is an introduction; the official docs are the reference manual.

An issue I see with this is that while Stack Overflow Docs may become the de-facto source for documentation, it can't be the authoritative source if official documentation exists. In some cases, like actual standards documents, the documentation is correct by definition: if ISO publishes a new Technical Corrigendum to the C standard that contradicts what's written on Stack Overflow, the Stack Overflow documentation instantly become incorrect, no matter how well written.

Even if the official documentation is considered non-normative, you still potentially can end up with situations where Stack Overflow documents the way a system actually works, but contradicts the official documentation. It could well be that the official documentation is still correct and there's a bug in the system. The best course of action in such cases is to contact the author and inform them of the inconsistency so they can deal with it, not to pick one of the inconsistent options and document that. If Stack Overflow becomes the de-facto source for documentation, it may create situations in which the bug can't be removed without confusing everyone who uses the Stack Overflow documentation.

Normal Stack Overflow works fine, since we can answer questions about a specific scenario that isn't mentioned in the documentation, and then reference the document (or set of documents) that relate to the problem. It's more or less explicit that the answers are subordinate to the formal documentation.

That said, I do think there is room here to supplement the official documentation in a way that the existing Stack Overflow does not. If Stack Overflow Docs concentrates on examples of common uses (carefully edited so as to not become exhaustive to the point of uselessness), this would help address a weakness of much of the existing documentation.

Several others have mentioned tutorials; I think that would be excellent, especially if said tutorials referenced the relevant parts of the official documentation in each section. Such references, coupled with the existing voting and commenting system, could help keep the tutorials and examples listed here at a higher level of accuracy than the ones that are basically "This is what I was told when I first learned how to use it, and I never questioned it".

So in summary, I think that creating a set of well-written, reliably-accurate examples and tutorials would greatly benefit the overall level of online documentation without running into the fragmentation issues that duplicating the documentation itself, since there's a clear division of purpose: Stack Overflow Docs is an introduction; the official documentation is the reference manual.

Source Link
Ray
  • 2.2k
  • 1
  • 14
  • 14

An issue I see with this is that while Stack Overflow Docs may become the de-facto source for documentation, it can't be the authoritative source if official documentation exists. In some cases, like actual standards documents, the documentation is correct by definition: if ISO publishes a new Technical Corrigendum to the C standard that contradicts what's written on SO, the SO docs instantly become incorrect, no matter how well written.

Even if the official documentation is considered non-normative, you still potentially can end up with situations where SO documents the way a system actually works but contradicts the official docs. It could well be that the official docs are still correct and there's a bug in the system. The best course of action in such cases is to contact the author and inform them of the inconsistency so they can deal with it, not to pick one of the inconsistent options and document that. If SO becomes the de-facto source for docs, it may create situations in which the bug can't be removed without confusing everyone who uses the SO documentation.

Normal Stack Overflow works fine, since we can answer questions about a specific scenario that isn't mentioned in the docs, and then reference the document (or set of documents) that relate to the problem. It's more or less explicit that the answers are subordinate to the formal documentation.

That said, I do think there is room here to suppliment the official documentation in a way that the existing Stack Overflow does not. If Stack Overflow Docs concentrates on examples of common uses (carefully edited so as to not become exhaustive to the point of uselessness), this would help address a weakness of much of the existing documentation.

Several others have mentioned tutorials; I think that would be excellent, especially if said tutorials referenced the relevant parts of the official documentation in each section. Such references, coupled with the existing voting and commenting system, could help keep the tutorials and examples listed here at a higher level of accuracy than the ones that are basically "This is what I was told when I first learned how to use it, and I never questioned it".

So in summary, I think that creating a set of well-written, reliably-accurate examples and tutorials would greatly benefit the overal level of online documentation without running into the fragmentation issues that duplicating the documentation itself, since there's a clear division of purpose: Stack Overflow Docs is an introduction; the official docs are the reference manual.