Skip to main content
replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
Source Link

One of two things happen next: either the community slows to a virtual halt, or a handful of dedicated users get down to the real work of building a community.

I fail to see a path forward that can reasonably be expected to accomplish this. Why?

A place for discussion is a necessary element for this. But it is not sufficient. You need to get a handful of users who are both knowledgable and motivated to build documentation and a community.

And I don't see that happening. Not with Docs.SO as it currently stands or is likely to stand in the immediate future. I can only speak for myself, but I imagine that others will agree with me on these statements:

I do not believe in Docs.SO.

I do not believe that Tag/Topic/Example is a sufficient categorization mechanism, even for example-focused documentation. I do not understand what "Topic" means or how much stuff should be in one. I do not believe that examples ought to be arbitrarily connected to each other, such that editing supposedly distinct examples should be considered a single edit.

Indeed, even if its current implementation were good, that wouldn't be enough. Because I do not believe in the very foundational idea of Docs.SO: that example-focused documentation can be used to create good, useful, and comprehensive documentation for a system of significant complexity.

I believe in neither the idea behind Docs.SO as a means for creating effective documentation, nor the current implementation of that idea. Docs.SO to me seems firmly aimed in the wrong direction, both in implementation and in concept.

I cannot say how many people agree with me on these statements. However, the fact that most experts appear to have deserted Docs.SO within weeks of its deployment suggest that I am probably not alone in these criticisms. StatementsStatements fromfrom othersothers also suggest that I'm probably not alone.

So what exactly is the benefit for experts to contribute to Docs.SO? They have to deal with a sub-standard mechanism for creating information (seriously, MediaWiki is better). They have to force their information into a design and organization scheme that you have arbitrarily imposed on them, instead of creating one that best fits the content being documented. And thanks to reputation, there is more of an incentive to post bad or plagiarized stuff than there is to focus on quality documentation.

What exactly are the advantages for using Docs.SO as a platform for creating documentation? What is the motivation for putting this stuff here, instead of literally anywhere else?

The "software skeleton" is precisely what is responsible for making Docs.SO unattractive to expert users. That it is "nearing completion" merely suggests that these flaws will never be fixed, that they're not considered "bugs" but "features".

So I cannot see how it is reasonable to expect experts to appear who are willing to "get down to the real work of building a community", given that the tools they have are so poor.

No matter how much it gets ignored, the fact remains that the Emperor is still naked.the Emperor is still naked.

One of two things happen next: either the community slows to a virtual halt, or a handful of dedicated users get down to the real work of building a community.

I fail to see a path forward that can reasonably be expected to accomplish this. Why?

A place for discussion is a necessary element for this. But it is not sufficient. You need to get a handful of users who are both knowledgable and motivated to build documentation and a community.

And I don't see that happening. Not with Docs.SO as it currently stands or is likely to stand in the immediate future. I can only speak for myself, but I imagine that others will agree with me on these statements:

I do not believe in Docs.SO.

I do not believe that Tag/Topic/Example is a sufficient categorization mechanism, even for example-focused documentation. I do not understand what "Topic" means or how much stuff should be in one. I do not believe that examples ought to be arbitrarily connected to each other, such that editing supposedly distinct examples should be considered a single edit.

Indeed, even if its current implementation were good, that wouldn't be enough. Because I do not believe in the very foundational idea of Docs.SO: that example-focused documentation can be used to create good, useful, and comprehensive documentation for a system of significant complexity.

I believe in neither the idea behind Docs.SO as a means for creating effective documentation, nor the current implementation of that idea. Docs.SO to me seems firmly aimed in the wrong direction, both in implementation and in concept.

I cannot say how many people agree with me on these statements. However, the fact that most experts appear to have deserted Docs.SO within weeks of its deployment suggest that I am probably not alone in these criticisms. Statements from others also suggest that I'm probably not alone.

So what exactly is the benefit for experts to contribute to Docs.SO? They have to deal with a sub-standard mechanism for creating information (seriously, MediaWiki is better). They have to force their information into a design and organization scheme that you have arbitrarily imposed on them, instead of creating one that best fits the content being documented. And thanks to reputation, there is more of an incentive to post bad or plagiarized stuff than there is to focus on quality documentation.

What exactly are the advantages for using Docs.SO as a platform for creating documentation? What is the motivation for putting this stuff here, instead of literally anywhere else?

The "software skeleton" is precisely what is responsible for making Docs.SO unattractive to expert users. That it is "nearing completion" merely suggests that these flaws will never be fixed, that they're not considered "bugs" but "features".

So I cannot see how it is reasonable to expect experts to appear who are willing to "get down to the real work of building a community", given that the tools they have are so poor.

No matter how much it gets ignored, the fact remains that the Emperor is still naked.

One of two things happen next: either the community slows to a virtual halt, or a handful of dedicated users get down to the real work of building a community.

I fail to see a path forward that can reasonably be expected to accomplish this. Why?

A place for discussion is a necessary element for this. But it is not sufficient. You need to get a handful of users who are both knowledgable and motivated to build documentation and a community.

And I don't see that happening. Not with Docs.SO as it currently stands or is likely to stand in the immediate future. I can only speak for myself, but I imagine that others will agree with me on these statements:

I do not believe in Docs.SO.

I do not believe that Tag/Topic/Example is a sufficient categorization mechanism, even for example-focused documentation. I do not understand what "Topic" means or how much stuff should be in one. I do not believe that examples ought to be arbitrarily connected to each other, such that editing supposedly distinct examples should be considered a single edit.

Indeed, even if its current implementation were good, that wouldn't be enough. Because I do not believe in the very foundational idea of Docs.SO: that example-focused documentation can be used to create good, useful, and comprehensive documentation for a system of significant complexity.

I believe in neither the idea behind Docs.SO as a means for creating effective documentation, nor the current implementation of that idea. Docs.SO to me seems firmly aimed in the wrong direction, both in implementation and in concept.

I cannot say how many people agree with me on these statements. However, the fact that most experts appear to have deserted Docs.SO within weeks of its deployment suggest that I am probably not alone in these criticisms. Statements from others also suggest that I'm probably not alone.

So what exactly is the benefit for experts to contribute to Docs.SO? They have to deal with a sub-standard mechanism for creating information (seriously, MediaWiki is better). They have to force their information into a design and organization scheme that you have arbitrarily imposed on them, instead of creating one that best fits the content being documented. And thanks to reputation, there is more of an incentive to post bad or plagiarized stuff than there is to focus on quality documentation.

What exactly are the advantages for using Docs.SO as a platform for creating documentation? What is the motivation for putting this stuff here, instead of literally anywhere else?

The "software skeleton" is precisely what is responsible for making Docs.SO unattractive to expert users. That it is "nearing completion" merely suggests that these flaws will never be fixed, that they're not considered "bugs" but "features".

So I cannot see how it is reasonable to expect experts to appear who are willing to "get down to the real work of building a community", given that the tools they have are so poor.

No matter how much it gets ignored, the fact remains that the Emperor is still naked.

Source Link
Nicol Bolas
  • 472k
  • 61
  • 186
  • 279

One of two things happen next: either the community slows to a virtual halt, or a handful of dedicated users get down to the real work of building a community.

I fail to see a path forward that can reasonably be expected to accomplish this. Why?

A place for discussion is a necessary element for this. But it is not sufficient. You need to get a handful of users who are both knowledgable and motivated to build documentation and a community.

And I don't see that happening. Not with Docs.SO as it currently stands or is likely to stand in the immediate future. I can only speak for myself, but I imagine that others will agree with me on these statements:

I do not believe in Docs.SO.

I do not believe that Tag/Topic/Example is a sufficient categorization mechanism, even for example-focused documentation. I do not understand what "Topic" means or how much stuff should be in one. I do not believe that examples ought to be arbitrarily connected to each other, such that editing supposedly distinct examples should be considered a single edit.

Indeed, even if its current implementation were good, that wouldn't be enough. Because I do not believe in the very foundational idea of Docs.SO: that example-focused documentation can be used to create good, useful, and comprehensive documentation for a system of significant complexity.

I believe in neither the idea behind Docs.SO as a means for creating effective documentation, nor the current implementation of that idea. Docs.SO to me seems firmly aimed in the wrong direction, both in implementation and in concept.

I cannot say how many people agree with me on these statements. However, the fact that most experts appear to have deserted Docs.SO within weeks of its deployment suggest that I am probably not alone in these criticisms. Statements from others also suggest that I'm probably not alone.

So what exactly is the benefit for experts to contribute to Docs.SO? They have to deal with a sub-standard mechanism for creating information (seriously, MediaWiki is better). They have to force their information into a design and organization scheme that you have arbitrarily imposed on them, instead of creating one that best fits the content being documented. And thanks to reputation, there is more of an incentive to post bad or plagiarized stuff than there is to focus on quality documentation.

What exactly are the advantages for using Docs.SO as a platform for creating documentation? What is the motivation for putting this stuff here, instead of literally anywhere else?

The "software skeleton" is precisely what is responsible for making Docs.SO unattractive to expert users. That it is "nearing completion" merely suggests that these flaws will never be fixed, that they're not considered "bugs" but "features".

So I cannot see how it is reasonable to expect experts to appear who are willing to "get down to the real work of building a community", given that the tools they have are so poor.

No matter how much it gets ignored, the fact remains that the Emperor is still naked.