Stack Overflow, a collaboratively edited question and answer site for programmers, has announced its plans to add documentation to the site:
“Lately we’ve been asking ourselves “what else could we do to improve developers’ lives on the internet?”. Jeff’s original announcement of Stack Overflow said this:
There’s far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We’d like to unlock all that. Let’s create something that makes it easy to participate, and put it online in a form that is trivially easy to find.
Stack Overflow has made all of that a lot better, but there’s one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better….
…We’re hoping we can improve documentation, not just move it under the stackoverflow.com domain.”
It will be fascinating to see how this project progresses – what issues they encounter, how they tackle these, and if the solutions work.
Joel Spolsky, the co-founder of Stack Overflow, famously wrote:
Users don’t have the manual, and if they did, they wouldn’t read it.
In fact, users can’t read anything, and if they could, they wouldn’t want to.(Source)
He developed Stack Overflow as a way of resolving these issues.
The Stack Overflow (SO) users who commented at the bottom the announcement have highlighted some of the issues that will need to be resolved:
“I’m concerned about the fragmentation this can cause. Some documentation sites like MSDN have both good and bad documentation. How do you see people decide on what documentation is good enough to not have to redo it on SO?Is one of the goals to eventually see work being done here go back upstream to the official documentation of a project? If so, I think attaching a CC license to it could cause a lot of headaches down the line. What if the official documentation is greatly improved, surpassing the quality of documentation on SO? Will you remove the content on SO?”
Stijn
“I think the concept of adding “Documentation” to SO (or an adjoining site) is deeply flawed. It attempts to solve the problem of “developers don’t like writing documentation” by having developers write documentation, and the problem of “people ask duplicate Questions instead of Googling” by expecting people to click a Documentation link in a Google search.”
TigerhawkT3
“If this is to be a success, I think it needs to address concrete problems that active question-answerers currently have with Stack Overflow. Problems like:
The endless flood of duplicate questions … which we know perfectly well have already been answered but it’s hard to find the canonical duplicate
No good place to put canonical explanations of things that someone didn’t actually ask about but need to know anyway as a consequence of their question.”Zwol
“As I see it, documentation, be it good or bad, is canon, information vetted by the developers. Treating user-submitted content as documentation risks confusion, obsolescence and, as Stijn points out, fragmentation.”
Peter Mortensen
Stack Overflow has developed a template for each topic, to ensure each topic contains key information:
Required:
- Examples
- Remarks
Optional:
- Syntax
- Parameters
It is also developing a browser-based authoring environment for creating the topics, based on Markdown and Prettify.
Will it work?
There is a demand from developers for more code examples, and it might work well as a supplementary source of examples. However, they have a number of challenges ahead of them.
What do you think?
Please share your thoughts below.
Leave a Reply