Run a mega-manual from Stackoverflow
Stackoverflow announced the launch of a new ambitious project: a documentation hub for all existing technologies. It is assumed that for each tag existing on the Stack it will be possible to create a section of documentation, and in this section post topics similar to the existing question-answer paradigm, but which are sections of documentation. It may turn out that the Stack will become for the open-source community the same standard platform for documentation, like, say, GitHab for sources.
As conceived by Jeff, Kevin and other founders of the site, this will allow users to create better documentation themselves than the authors of this or that technology often provide. Then programmers will not be able to leave the Stack website at all, where they already spend a lot of time solving their daily problems. Custom proofreading, voting, code samples, a single search, reputation motivation - there is hope that all this will help to create an order of magnitude better and more demanded documentation, and for all the technologies at once.
The authors especially rely on code samples. Indeed, the number of useful code examples on the Stack exceeds any official documentation on any technology. This is due to the fact that it is quite difficult to write examples; each requires great thought and time. Write as many examples as only many thousands of users on Stack could, and even a good documenting team would not be able to compete with well-organized crowd.
Often, when a product is released, the documentation is published, the number of useful code examples remains the same, at least until the next version of the product, when developers update the documentation. The stack logically assumes that constantly updated documentation can make a developer’s life better.
')
The founders also claim that the documentation format used in most projects is outdated, that is, the user interface itself. Most of the documentation systems of programming languages, libraries, API will inherit the ideas of Javadocs twenty years ago. Links in such systems are usually local and are lost with versions. Stekovtsy promise to solve both problems, make perpetual global links and a modern user interface inherited from the interface of the main question-answer site and run in by millions of users. Threatened that their uay / uix will be the best in the world.
In fact, the people at Stack are very practical, they have completely different considerations. The problem that constantly torments users and owners of Stack is too broad and off-topic. In the comments, battles have been going on for years because people want to ask questions “in general,” for example, “what would you advise to read”. A separate programmers hub was created, but it is not particularly popular, and the stream of “off-topics” and “T-broads” does not weaken. So: there is hope that most of these questions will go to the documentation instead of fighting them, they will become a useful part of the network.
The articles themselves on the Stekoferflow will now be able to refer to the documentation on the Stack itself. This will solve a very serious problem: broken links. Links to documentation are in a huge number of questions and answers, and the percentage of their “bitness” and obsolescence grows over the years, as official documentation constantly mutates in content or migrates by reference.
According to statistics, a lot of questions on the stack, in general, arise only due to the fact that the official documentation does not have or low-quality infa on some topic. Moreover, such questions can be asked dozens and hundreds of times, and they have to be deleted again and again, spending time and resources of moderators and the community as a whole. It is hoped that in such cases the community will respond by creating relevant articles in the docks and the flow of these duplicates will be reduced, freeing the creative forces of the community to more useful things.
Another crucial issue that may improve as a result is the opportunity to benefit. Now there are a lot of people using Stack who want to write something useful for others, which they understand very well, but they cannot, because they cannot find suitable questions or do not want to participate in the race of answers. You know, there is this on the Stack; in pursuit of reputation, people rush to respond with maximum speed, often using different tricks to bring their answer to the top. Now you can slowly create topics for documentation on a huge number of topics and, by the way, get votes in reputation.
The founders are still not sure of the success of this undertaking, many ambitious projects fail in this world. Therefore, they start slowly, while only private beta is open, on which all technologies are tested: forms, search, display, and so on.
So far the idea is this: a tag is taken from existing ones already on the Stekoflowflow and pages are created for it, the official name of which is “topics”. Each topic has a title, examples and notes, as well as optional sections, which can be any number of times. The main emphasis is, of course, on examples. As the clear example illustrating the topic is what the developer is looking for in the documentation (and does not find it in most cases, hence Stack’s popularity).
Examples can be “collapsed” (collapse) global links can lead not only to the whole topic, but also to a separate example. In general, the editor will be new, although it is similar to the editor of the questionnaire-response. McDown, backlight, enlarged window. In addition to topics, by the way, it will be possible to create requests (requests), you can vote for them and top requests must make you want to write topics on them among visitors. How all this will specifically affect not reputation is not yet clear. However, it is already clear: the reputation of the question part of the site and the reputation at the docks will be common!
Of course, there is confusion in the motives. On the one hand, the founders rush with phrases in the spirit of “one ring (docs) to rule them all”, on the other hand they say that there is no need to compete with good existing documentation, but only to work where there are no high-quality documentation. All this raises many questions among the people.
Another question is, where to post your questions and problems now, to the new request of the topic or the old questionnaire? This can cause considerable confusion, for example, “how to put two lines on Java” is this where, in questions-answers or is it a request for a new article in the dock? It is not yet clear, although guides (rules) on this topic are being pushed.
Importing articles from existing documentation is prohibited. There is a licensing policy, but here I will not discuss it, since the article is introductory.
A wide discussion has unfolded, I will cite a number of questions that have received a wide response.
They ask: you say that if the project has good documentation, then you should not do the docks for this project on the stack, but what if the docks were created on the stack, and then the project got its own cool documentation? Will the stack documentation be erased?
The question is tricky, but Kevin logically explained: what, they say, create voting systems, let the community decide what to erase and what to leave.
Another question is what to do in systems like .NET, where there are many versions and for each of their own large documentation. The answer is that the technology versions will also be taken into account by special means! So far, more detailed information about how it will be - no.
The biggest bunch of pluses received a comment (although technically this is the answer) of a person who posted a comic from three screenshots, on the first he typed in google “node.js write file”, and the first link on top leads to Stack, on the second page opened by this link, where the required example of writing to the file is immediately thrown, and on the third page of the official documentation on Node.js, where the list of supported functions is typical for this resource and it is absolutely not clear what to read further. That is, people are looking for examples. But in itself it does not prove the need for a new site.
People are very worried that there will be confusion between official documentation and documentation on the Stack. Some believe that it will “survive the strongest”, others think that the official documentation will be only for hardcore players and those who write docks for Stack, and the majority will use the latter, and the founders of Stack themselves consider that it is best to officially migrate official docks to Stack platform! Having a single, global, run-in user interface and a huge public reading and editing should be convenient to the creators of technology, is not it? The creators of open-source projects, probably the first to take advantage of this opportunity.
Some worry that concentrating all the documentation on one resource can turn the Stack into Evil Corporation. But others answer that, in essence, Stack is just hosting, all power on it belongs to society and voting mechanisms and it’s not clear how this can be evil.
Many people think that documentation is too broad a concept and suggest that Stack concentrate solely on examples. This also raises serious questions, because a rare example is completely without textual support. Moreover, it is clear that although examples are a killer feature of the new project, there are also off-topic and two broads, broken links, the ability to contribute to those who are not able to and other absolutely practical features.
They propose to make another site for tutorials and haut.
People are also worried that documentation, especially official, should be perceived as ultimate truth, and on the Stack it will become the subject of discussion, and where are the guarantees that it will correspond to reality, especially when developers write one thing, in reality, another, and write the code is still recommended by the documentation, even if it is known that, for example, there is a cant in the compiler. To which the people respond with a sakrasm, rightly pointing out that there is little official documentation in which there would be no mistakes, confusion, non-working examples, and so on. One person picked up the pluses by saying something like what, they say, if you like it when documentation is something like the Bible, you can install MSDN from a CD.
A lot of advantages received a comment that a bunch of developers crawling around the site (I remembered the notorious imaginary monkeys at the typewriter War and Peace) never create high-quality documentation, because professionals who know how to structure it all should do it , issue, aware of the complexity and responsibility of the task. Among other things, the documentation is the source of the programmer style and problem-solving patterns, and create such docks that do not just show how to solve the problem, but explaining how to solve it from the point of view of technology developers can only professional dock writers working in close contact with the developers of this technology. . Although there was no popular answer to this question, but some indicated that when thousands of programmers use technology and solve all problems connected with it, they create docks just like other users of this technology and it’s not a fact that “these Professional writers in close contact with the developers "are really necessary. Perhaps this issue is more concerned about the professional dokoppekopateli, because there are so many of them and they get money. By the way, their work may not disappear, they will simply be paid for "sitting on the stack."
I was very pleased with one person by citing examples of off-topics that are constantly being killed on Stack, but which “everyone should know”, and who need to find a place on the site, and which, by the way, lead to many questions that could not be, know people these basic things: “never use scanf”, “the type-based aliasing rules are asymmetric” (I find it difficult to translate) and “you should not try to solve this problem with a shell script”.
People who wrote docks for open source projects spoke in a spirit of writing official docks much more pleasantly than for “some forums and wikis,” trying to make various quasi-rational arguments, for example, that authors of open projects like being associated with clarifying issues. But somehow it does not convince me very much.
The official discussion thread in English is on Mete, everyone is welcome to take part: meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow?cb=1
This is the situation, we are waiting for development. For myself, I have not yet decided whether this is good or bad, but one thing I can say for sure, I am very interested in what will come of this (not). It would be interesting to compare the opinions of the English-speaking community, with what our Russian-speaking thinks, do not hesitate to leave your comments! And yet, in conclusion, dear readers, you are invited to a small survey:
As conceived by Jeff, Kevin and other founders of the site, this will allow users to create better documentation themselves than the authors of this or that technology often provide. Then programmers will not be able to leave the Stack website at all, where they already spend a lot of time solving their daily problems. Custom proofreading, voting, code samples, a single search, reputation motivation - there is hope that all this will help to create an order of magnitude better and more demanded documentation, and for all the technologies at once.
The authors especially rely on code samples. Indeed, the number of useful code examples on the Stack exceeds any official documentation on any technology. This is due to the fact that it is quite difficult to write examples; each requires great thought and time. Write as many examples as only many thousands of users on Stack could, and even a good documenting team would not be able to compete with well-organized crowd.
Often, when a product is released, the documentation is published, the number of useful code examples remains the same, at least until the next version of the product, when developers update the documentation. The stack logically assumes that constantly updated documentation can make a developer’s life better.
')
The founders also claim that the documentation format used in most projects is outdated, that is, the user interface itself. Most of the documentation systems of programming languages, libraries, API will inherit the ideas of Javadocs twenty years ago. Links in such systems are usually local and are lost with versions. Stekovtsy promise to solve both problems, make perpetual global links and a modern user interface inherited from the interface of the main question-answer site and run in by millions of users. Threatened that their uay / uix will be the best in the world.
In fact, the people at Stack are very practical, they have completely different considerations. The problem that constantly torments users and owners of Stack is too broad and off-topic. In the comments, battles have been going on for years because people want to ask questions “in general,” for example, “what would you advise to read”. A separate programmers hub was created, but it is not particularly popular, and the stream of “off-topics” and “T-broads” does not weaken. So: there is hope that most of these questions will go to the documentation instead of fighting them, they will become a useful part of the network.
The articles themselves on the Stekoferflow will now be able to refer to the documentation on the Stack itself. This will solve a very serious problem: broken links. Links to documentation are in a huge number of questions and answers, and the percentage of their “bitness” and obsolescence grows over the years, as official documentation constantly mutates in content or migrates by reference.
According to statistics, a lot of questions on the stack, in general, arise only due to the fact that the official documentation does not have or low-quality infa on some topic. Moreover, such questions can be asked dozens and hundreds of times, and they have to be deleted again and again, spending time and resources of moderators and the community as a whole. It is hoped that in such cases the community will respond by creating relevant articles in the docks and the flow of these duplicates will be reduced, freeing the creative forces of the community to more useful things.
Another crucial issue that may improve as a result is the opportunity to benefit. Now there are a lot of people using Stack who want to write something useful for others, which they understand very well, but they cannot, because they cannot find suitable questions or do not want to participate in the race of answers. You know, there is this on the Stack; in pursuit of reputation, people rush to respond with maximum speed, often using different tricks to bring their answer to the top. Now you can slowly create topics for documentation on a huge number of topics and, by the way, get votes in reputation.
The founders are still not sure of the success of this undertaking, many ambitious projects fail in this world. Therefore, they start slowly, while only private beta is open, on which all technologies are tested: forms, search, display, and so on.
So far the idea is this: a tag is taken from existing ones already on the Stekoflowflow and pages are created for it, the official name of which is “topics”. Each topic has a title, examples and notes, as well as optional sections, which can be any number of times. The main emphasis is, of course, on examples. As the clear example illustrating the topic is what the developer is looking for in the documentation (and does not find it in most cases, hence Stack’s popularity).
Examples can be “collapsed” (collapse) global links can lead not only to the whole topic, but also to a separate example. In general, the editor will be new, although it is similar to the editor of the questionnaire-response. McDown, backlight, enlarged window. In addition to topics, by the way, it will be possible to create requests (requests), you can vote for them and top requests must make you want to write topics on them among visitors. How all this will specifically affect not reputation is not yet clear. However, it is already clear: the reputation of the question part of the site and the reputation at the docks will be common!
Of course, there is confusion in the motives. On the one hand, the founders rush with phrases in the spirit of “one ring (docs) to rule them all”, on the other hand they say that there is no need to compete with good existing documentation, but only to work where there are no high-quality documentation. All this raises many questions among the people.
Another question is, where to post your questions and problems now, to the new request of the topic or the old questionnaire? This can cause considerable confusion, for example, “how to put two lines on Java” is this where, in questions-answers or is it a request for a new article in the dock? It is not yet clear, although guides (rules) on this topic are being pushed.
Importing articles from existing documentation is prohibited. There is a licensing policy, but here I will not discuss it, since the article is introductory.
A wide discussion has unfolded, I will cite a number of questions that have received a wide response.
They ask: you say that if the project has good documentation, then you should not do the docks for this project on the stack, but what if the docks were created on the stack, and then the project got its own cool documentation? Will the stack documentation be erased?
The question is tricky, but Kevin logically explained: what, they say, create voting systems, let the community decide what to erase and what to leave.
Another question is what to do in systems like .NET, where there are many versions and for each of their own large documentation. The answer is that the technology versions will also be taken into account by special means! So far, more detailed information about how it will be - no.
The biggest bunch of pluses received a comment (although technically this is the answer) of a person who posted a comic from three screenshots, on the first he typed in google “node.js write file”, and the first link on top leads to Stack, on the second page opened by this link, where the required example of writing to the file is immediately thrown, and on the third page of the official documentation on Node.js, where the list of supported functions is typical for this resource and it is absolutely not clear what to read further. That is, people are looking for examples. But in itself it does not prove the need for a new site.
People are very worried that there will be confusion between official documentation and documentation on the Stack. Some believe that it will “survive the strongest”, others think that the official documentation will be only for hardcore players and those who write docks for Stack, and the majority will use the latter, and the founders of Stack themselves consider that it is best to officially migrate official docks to Stack platform! Having a single, global, run-in user interface and a huge public reading and editing should be convenient to the creators of technology, is not it? The creators of open-source projects, probably the first to take advantage of this opportunity.
Some worry that concentrating all the documentation on one resource can turn the Stack into Evil Corporation. But others answer that, in essence, Stack is just hosting, all power on it belongs to society and voting mechanisms and it’s not clear how this can be evil.
Many people think that documentation is too broad a concept and suggest that Stack concentrate solely on examples. This also raises serious questions, because a rare example is completely without textual support. Moreover, it is clear that although examples are a killer feature of the new project, there are also off-topic and two broads, broken links, the ability to contribute to those who are not able to and other absolutely practical features.
They propose to make another site for tutorials and haut.
People are also worried that documentation, especially official, should be perceived as ultimate truth, and on the Stack it will become the subject of discussion, and where are the guarantees that it will correspond to reality, especially when developers write one thing, in reality, another, and write the code is still recommended by the documentation, even if it is known that, for example, there is a cant in the compiler. To which the people respond with a sakrasm, rightly pointing out that there is little official documentation in which there would be no mistakes, confusion, non-working examples, and so on. One person picked up the pluses by saying something like what, they say, if you like it when documentation is something like the Bible, you can install MSDN from a CD.
A lot of advantages received a comment that a bunch of developers crawling around the site (I remembered the notorious imaginary monkeys at the typewriter War and Peace) never create high-quality documentation, because professionals who know how to structure it all should do it , issue, aware of the complexity and responsibility of the task. Among other things, the documentation is the source of the programmer style and problem-solving patterns, and create such docks that do not just show how to solve the problem, but explaining how to solve it from the point of view of technology developers can only professional dock writers working in close contact with the developers of this technology. . Although there was no popular answer to this question, but some indicated that when thousands of programmers use technology and solve all problems connected with it, they create docks just like other users of this technology and it’s not a fact that “these Professional writers in close contact with the developers "are really necessary. Perhaps this issue is more concerned about the professional dokoppekopateli, because there are so many of them and they get money. By the way, their work may not disappear, they will simply be paid for "sitting on the stack."
I was very pleased with one person by citing examples of off-topics that are constantly being killed on Stack, but which “everyone should know”, and who need to find a place on the site, and which, by the way, lead to many questions that could not be, know people these basic things: “never use scanf”, “the type-based aliasing rules are asymmetric” (I find it difficult to translate) and “you should not try to solve this problem with a shell script”.
People who wrote docks for open source projects spoke in a spirit of writing official docks much more pleasantly than for “some forums and wikis,” trying to make various quasi-rational arguments, for example, that authors of open projects like being associated with clarifying issues. But somehow it does not convince me very much.
The official discussion thread in English is on Mete, everyone is welcome to take part: meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow?cb=1
This is the situation, we are waiting for development. For myself, I have not yet decided whether this is good or bad, but one thing I can say for sure, I am very interested in what will come of this (not). It would be interesting to compare the opinions of the English-speaking community, with what our Russian-speaking thinks, do not hesitate to leave your comments! And yet, in conclusion, dear readers, you are invited to a small survey:
Source: https://habr.com/ru/post/266731/
All Articles