Docs is broken: Writing Docs we actually need

Docs is broken: Writing Docs we actually need

<strong>The current system rewards writing documentation that is already covered by the official docs. Meanwhile, popular libraries without good official docs are undercontributed. The system is broken, and it needs fixing.</strong>&nbsp;This result runs counter to how Docs was pitched:

The current system rewards writing documentation that is already covered by the official docs. Meanwhile, popular libraries without good official docs are undercontributed. The system is broken, and it needs fixing. This result runs counter to how Docs was pitched:

Q: What should be documented?
A: Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation, not just moving them onto Stack Overflow. --announcement in Aug 2015

Let's take as an example the Boost library. The official documentation is pretty lackluster, consisting of 404'd links and unclear explanations. This is when Stack Overflow documentation would be most useful. Right now, the Boost documentation has one example with one topic.

The current reputation system encourages people to write documentation that don't need to be rewritten. The front page shouldn't be filled with C#, Android, and Python - they should be filled with the topics without good official documentation, like Boost or LEMON. The popular topics are popular because they are easy to write, not because there is an actual need for the documentation.

The Boost Python documentation (and the Boost documentation in general) are very short and don't have many examples. It would take several hours digging through the reference guide and source code to do anything beyond what is described in the tutorial. We need to pool our knowledge to save people from those hours of digging.

We need to have a way to draw attention to a topic. Otherwise, topics like the Boost documentation would never grow, and developers would continue to get frustrated.

How else should we encourage users to contribute to undercontributed (for lack of better word) topics?

If you think that there aren't documentation topics that aren't fully covered by the official documentation, just look at the LEMON graph library or my aforementioned Boost documentation. The documentation for one of the core features (Map data types) is still under construction and the current examples won't compile. They've been in such a state for years.

Right now, the topics people contribute to most are already covered by the official documentation, while the topics people contribute to the least are the ones that aren't covered by the official documentation. This is because it is easy to write documentation when there is a clear official documentation, and it is hard to do so when there isn't - you'll have to spend several hours navigating the source code for clues. The popular documentation is popular because it is easy to write.

Summary

Whatever the solution, I believe that the current system is broken. It encourages making documentation that are covered by the official documentation. It puts topics in the spotlight simply because they're popular, not because they need contributors. It rewards those who contribute to popular documentation, not the documentation that need contribution. It should reward those that contribute to the documentation that needs it the most, not the most popular ones. Which, by definition of "popularity" already have plenty of contribution.

One prime example is Boost, likely the #1 used C++ library, with bad official documentation and only one example in Stack Overflow Documentation.

The system rewards contributing to documentation that don't need contribution, and buries documentation that needs it very deeply.

It does the opposite of what it should be doing.

The current system is broken. It needs fixing. How?

Stack Overflow docs should be replacing bad docs, not rewriting already good docs.

The documentation you see are the documentation that are easy to write. The documentation that are hard to write are hidden. This is why (quoting Louis) someone can say "I've not seen one bit of Docs that was not already covered perfectly in official or as-official-as-it-gets community-maintained documentation".

I encourage you to post an answer - it'll take more than implementing a single answer to fix this problem.

I apologize for the repetition - it is needed to avoid misunderstanding unfortunately.

If you want more examples, see CMake. Widely used, with lackluster documentation. (not a single example given for something as important as include directories!). And the Stack Overflow Docs are currently minimal at best.

Clarification: The things I said about Boost.python apply to Boost in general, not just for the Python submodule.

Angular 9 Tutorial: Learn to Build a CRUD Angular App Quickly

What's new in Bootstrap 5 and when Bootstrap 5 release date?

Brave, Chrome, Firefox, Opera or Edge: Which is Better and Faster?

How to Build Progressive Web Apps (PWA) using Angular 9

What is new features in Javascript ES2020 ECMAScript 2020

Top Python Development Companies | Hire Python Developers

After analyzing clients and market requirements, TopDevelopers has come up with the list of the best Python service providers. These top-rated Python developers are widely appreciated for their professionalism in handling diverse projects. When...

Python GUI Programming Projects using Tkinter and Python 3

Python GUI Programming Projects using Tkinter and Python 3

Guide to Python Programming Language

Guide to Python Programming Language