Doc: Restructering the documentation page
Moving the discussion from !8868 (closed).
I want to discuss some potential improvements to the CMake
documentation. First a few issues that I see
Some issues
- Top-level help directory (https://cmake.org/cmake/help/latest/index.html) is a bit wordy for new-comers. First-time visitors could be classified in: Project users, Project developers and Advanced/CMake developers. In principle there are sections to guide each type of users 1, but it is in a text body. I believe it is more helpful to add some sections for these individual sections like
User guide
,Project developer guide
,Advanced guide
or something similar - There is little distinction between the reference pages and guide pages. I think this is more due to the theme, but some reordering of the headings and TOC could also help visualize where you are and how to get back
- The CMake sphinx theme is a bit old-looking when we compare with the ones in https://sphinx-themes.org/, e.g.
furo
(no dark-mode, quick-navigation etc.) - The sphinx theme can be ambiguous. E.g. when rendering
versionadded
, it is not made clear which section of the text corresponds to that block - Guides are comprehensive. It is nice that there is so much information, but it could use a
tldr
section, ahow-to
/faq
section, etc. - We should highlight the current recommended standards for
Project developers
so they can have a place to get up to speed. E.g. theFetchContent
-find_package
interoperability
Suggested actions
- Try out other sphinx themes
- Restructure the TOC. We can add
sphinx-redirects
to maintain the old documentation links - Add
tldr
and other quick-referencing navigations. Something like this where you have a quick access to the common tasks forUser guide
could be helpful
Edited by Cristian Le