Quality-first documentation control #9860
Description
It is incredible how much amazing commendable documentation we have written out for PaddlePaddle. However, while we have accumulated a large amount of individually good documentation, this doesn’t necessarily result in a COHERENT documentation for the user. That is because we have a relatively lax policy on what documentation gets to show on the site in what order. And that is because we have applied the same git check-in rules on documentation as we have on code contribution. This was okay until now since we needed a lot of documentation from a large number of contributors.
This is not working any longer. Even without conducting user testing, any visitor is able to visit the website and get extremely confused by the navigation, and on each link, find a completely different structure to the one he was reading just before. Content is experience, and experience cannot be moderated by everyone without any difficult design choices. High-quality documentation experience requires strong design choices, just the way cpplint and other pre-commit hooks strive for clear software design.
Suggestion: We come up with a set of general guidelines on what constitutes quality and how to write documentation with clear points. Only a select group of people get to make decisions on what documentation becomes public facing. Based on shared guidelines, they strictly moderate the quality and coherence of the documentation. This often means that just adding a link to the design doc at an arbitrarily place in the ToC will no longer be the solution. Constantly gauging the user needs and gaps and opportunities in the documentation shall be necessary.
And if the developer is unable to take on the effort of considering all these complexities, dedicated people close to the user needs write high-quality documentation content. The latter will most certainly solve this issue.
Suggestion 2: Bringing up an old suggestion that was closed. In 2017, the idea of using sitemaps was proposed. Very simple idea: instead of backward-engineering Sphinx ToC with hacks to generate PaddlePaddle.org menus, each repo has a JSON schema that maps 1-to-1 to the exact way content is organized on the website. Since the website is the only way to render documentation, the Sphinx route seems unnecessary and vastly inefficient. This has also resulted in a very convoluted custom-hardcoded-logic PaddlePaddle.org codebase, that has resulted in a large number of tiny patches (https://github.com/PaddlePaddle/PaddlePaddle.org/issues?utf8=%E2%9C%93&q=is%3Aissue+author%3Ashanyi15+), and which will continue to be grow if we don’t make a stable solution today.
A sitemaps approach makes it extremely straightforward to figure out why their documentation is not showing an intended.
Another place where this issue has been analyzed in depth: https://github.com/PaddlePaddle/PaddlePaddle.org/wiki/Unified-Information-Architecture-Proposal