Project Description

This project is a continuation of the HW2023 activities.

It is imagined as a collection of random changes to the documentation files in order to rid them of cluttered in the content, outdated comments, inconsistent style (minor issues), unused parameters, duplications, etc.

Due to their nature, these issues do not represent the problem for the documentation in terms of the content itself or the building process, and are a natural outcome of the fast-growing body of content. Therefore, occasional deep clean-up is both desired and needed.

These changes are mostly related to the quality and style of the raw files.

Most represent a good-first-issue for those interested in trying to contribute to the documentation.

If you want to contribute, please keep in mind to:

• make all changes in small increments
• if making several changes at once, make sure they are similar in nature, i.e. in group the changes by the type of change (don't mix the changes that are very different)
• PRs affecting too many different changes or more than one book will be rejected

Goal for this Hackweek

• regular deep clean-up
• create an opportunity to contribute to the Uyuni documentation

Issues to work on

1 External list

• create a list of all external links in the documentation
• check if they are up-to-date
• define who creates a request for the external link change

2 Architecture parameters

• check if all architecture parameters are used; remove unused ones
• check for the duplicates

3 Existing snippets

• review all snippets
• are they all used?
• if the snippetis used only once - decide if we should keep the snippet in that case, or move it as the direct content to the relevant file
• tidy up the snippet if possible (remove comments, check line spacing)

4 Titles capitalizations

• Only first letter needs to be capitalized (master branch only for now)
• Check: Chapters, paragraphs, procedures
• Work in this order: first fix all page titles and navigation - book by book, then move to chapters, paragraphs and procedures (file by file)

5 Comments

• check ALL comments, book by book. Most relevant: Client Config Guide, Install and Upgrade Guide, Admin Guide. Use blame command to see when they were added. (If older than 2 years, they are likely candidate to be removed completely.)
• check all FIXME comments. Fix them, or delete them.
• check all comments with the authors' initials: LB, KE, JC, OM

6 Documentation analysis:

• images and tables - create a list, check if they are actually necessary, or they need updating, check for the duplicates, can we come up with the Best Practice?
• mark which images are version dependent (thus having priority for updating), and which are more generic

7 - Admonitions review

• When there are too many admonitions on the page, it beats their purpose. Review them all, especially on the newer pages and on the client installation related pages. Reduce as much as possible.

8 - Everything else

• Check if we really need titles for the admonitions. In the past, we had agreed to avoid them.
• Wording: Use full words, e.g replace 'sync' with 'synchronize'.

...