Uploaded image for project: 'Red Hat Advanced Cluster Management'
  1. Red Hat Advanced Cluster Management
  2. ACM-4427

Not worked: VolSync docs needs rewrite/architecture overhaul 2.8

XMLWordPrintable

    • 7
    • False
    • Hide

      None

      Show
      None
    • False
    • No

      Always look at the current documentation to describe the change that is needed. Use the source or portal link for Step 3:

       - Use the Customer Portal:

      https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.7/html/add-ons/add-ons-overview#volsync

       - Use the GitHub link to find the staged docs in the repository:

      https://github.com/stolostron/rhacm-docs/tree/2.8_stage/add-ons/volsync

      https://github.com/stolostron/rhacm-docs/tree/2.8_stage/add-ons

      Describe the changes in the doc and link to your dev story: Backup and restore docs overhaul (tech debt)

      Provide info for the following steps:

      1. - [x] Mandatory: Choose the documentation release (Published releases are refreshed ~weekly after publication).

            - [x] ACM 2.8

      2. - [x] Mandatory: Choose the type of documentation change.

            - [ ] New topic in an existing section or new section
            - [x] Update to an existing topic

      3. - [x] Mandatory for bugs: What is the diff? Clearly define what the problem is, what the change is, and link to the current documentation: https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.7/html/add-ons/add-ons-overview#volsync

       

      The VolSync docs need to be reworked to align with the rest of our modular docs. Some of the current issues:

       

      • File name issues: Rename volsync to volsync_intro
      • volsync_replicate file is too long (over 560 lines, recommend 300 lines or less per file). It contains topics that should be separate (for example install). Check our other docs to see how to structure the topics and make them modular as described here: https://redhat-documentation.github.io/modular-docs/
      • There are several style issues, many topics will need to be rewritten for conciseness and current IBM Style. For example, "It can be helpful when distributing data to multiple locations." needs to be rewritten to adhere to the style guide.
      • Several more style issue examples found in VolSync docs that need to be addressed include:
        • Some prompts are formatted wrong by separating the prompt from the stated goal (Should be: To do this and that, complete the following steps...)
        • Conceptual information is inserted between steps in a confusing manner -> Recommend separating conceptual information where possible
        • Single replacement prompts are listed after command examples instead of being part of the initial command prompt. When there are multiple variables to replace, use the new numbering system (<1>, <2> etc.) that we discussed.
        • Lengthy sentences with unnecessary wording throughout the book (check IBM Style and other sections in our docs like Submariner for guidance)
        • Tables are built horizontally instead of vertically -> Build them vertically to align with the rest of our docs
      • Use less inline links and instead create an Additional resources topic.
      • Use this opportunity to review the entire book for technical accuracy. Make sure to update examples where necessary.
      • Be aware of the upstream docs. Seems like most of the content originated from an old version of he upstream docs. Make sure that what we have now is updated where necessary: https://volsync.readthedocs.io/en/latest/index.html (notice how even they have a separate section for install)

       

      4. - [x] Mandatory for GA content:
                  
             - [x] Add steps and/or other important conceptual information here: 
             

      See Submariner reworked docs as an example. VolSync docs needs a similar architecture: https://github.com/stolostron/rhacm-docs/tree/2.8_stage/add-ons/submariner

              chrisadawson Christopher Dawson
              rh-ee-ofischer Oliver Fischer
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Created:
                Updated:
                Resolved: