Project Description

This project is planned 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.

The ones that are a good-first-issue listed at the top and are marked with (*).

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

• create an issue in github to indicate what you want to work on, to avoid duplication of work
• make all changes in small increments
• group the changes by the type of change (don't mix the changes that are different in nature)
• 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 documenattion
• 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(*) Quick Start Guide - create as a snippet?

• revisit the option of having a snippet that is overarching all books (currently not possible)
• if possible, see if Quick Start Guide and Install Guide instructions can be chunked up and relevant pages created from the sequences of shared snippets
• if not possible, look into the lowest possible maintenance process of these files (their content overlaps significantly)

5(*) 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)

6(*) 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

7 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

8 - To be added...