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.


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.


Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

Basic Data Types in Python | Python Web Development For Beginners

In the programming world, Data types play an important role. Each Variable is stored in different data types and responsible for various functions. Python had two different objects, and They are mutable and immutable objects.

How To Compare Tesla and Ford Company By Using Magic Methods in Python

Magic Methods are the special methods which gives us the ability to access built in syntactical features such as ‘<’, ‘>’, ‘==’, ‘+’ etc.. You must have worked with such methods without knowing them to be as magic methods. Magic methods can be identified with their names which start with __ and ends with __ like __init__, __call__, __str__ etc. These methods are also called Dunder Methods, because of their name starting and ending with Double Underscore (Dunder).

Python Programming: A Beginner’s Guide

Python is an interpreted, high-level, powerful general-purpose programming language. You may ask, Python’s a snake right? and Why is this programming language named after it?

Hire Python Developers

Are you looking for experienced, reliable, and qualified Python developers? If yes, you have reached the right place. At **[]( "")**, our full-stack Python development services...

Python any: How to Check If Element is Iterable or Not

Python any() function returns True if any element of an iterable is True otherwise any() function returns False. The syntax is any().