Uploaded image for project: 'SAFe Program'
  1. SAFe Program
  2. SP-3648

Address internal feedback on SDP documentation

Change Owns to Parent OfsSet start and due date...
    XporterXMLWordPrintable

Details

    • Enabler
    • Must have
    • PI20
    • COM SDP SW
    • None
    • True
    • Data Processing
    • Hide

      See Why?

      Show
      See Why?
    • Hide

      See What?

      Show
      See What?
    • Intra Program
    • 2
    • 2
    • 0
    • Team_NALEDI
    • Sprint 5
    • Hide

      The outcomes of the feature are related to the points below.

      1. Poor introduction.
      2. Needs a list of functionality the system currently supports in a language that talks to the way others will use SDP.
      3. Needs an easy way to find the documented public API, e.g. where to find what it means when the SDP subarray reports its health state is OK.
        • A link to the publicly available API documentation was added to the end of the Tango Interface documentation. This can be found here.
        • The MR is the same as point 2.
      4. Missing easy to find documentation of SDP UIs (signal displays, Taranta dashboards). Needs to link to data product dashboard documentation.
      5. Not easy enough to find out how to use SDP for key use cases.
        • This was done as a part of point 2.
      6. Information is duplicated, e.g. instructions for operating the SDP in a number of pages in the "Running the SDP" and "Using the SDP" sections. Reorganise the pages to remove the duplication and inconsistencies as far as possible. Possible arrangement of sections:
      7. Information on installing and testing in Minikube is prominent in older pages. The standard instructions should be about installing SDP in SKAO-managed clusters (STFC cloud, PSIs, ITFs) and treat Minikube as a special case (see next point).
      8. Revise Minikube-related documentation to use standard SKAO Minikube deployment instead of custom configuration.
        • See point 7.
      9. Design section is out of date. Components and Modules pages are missing information on queue connector Tango devices, data queues (Kafka) and QA components.
      Show
      The outcomes of the feature are related to the points below. Poor introduction. The introduction was updated and can be seen in this documentation .  The MR can be found at https://gitlab.com/ska-telescope/sdp/ska-sdp-integration/-/merge_requests/238 Needs a list of functionality the system currently supports in a language that talks to the way others will use SDP. A list of current and future functionality can be found in the introduction of the SDP .  The MR can be found here: https://gitlab.com/ska-telescope/sdp/ska-sdp-integration/-/merge_requests/249 Needs an easy way to find the documented public API, e.g. where to find what it means when the SDP subarray reports its health state is OK. A link to the publicly available API documentation was added to the end of the Tango Interface documentation. This can be found here . The MR is the same as point 2. Missing easy to find documentation of SDP UIs (signal displays, Taranta dashboards). Needs to link to data product dashboard documentation. Links were added to the relevant documentation pages ( Signal Display and Taranta dashboards and Data Product Dashboard ) The MR can be found at: https://gitlab.com/ska-telescope/sdp/ska-sdp-integration/-/merge_requests/232 Not easy enough to find out how to use SDP for key use cases. This was done as a part of point 2. Information is duplicated, e.g. instructions for operating the SDP in a number of pages in the "Running the SDP" and "Using the SDP" sections. Reorganise the pages to remove the duplication and inconsistencies as far as possible. Possible arrangement of sections: Design Installation Operation Development Troubleshooting This was done by the ORCA team: https://gitlab.com/ska-telescope/sdp/ska-sdp-integration/-/merge_requests/222 Information on installing and testing in Minikube is prominent in older pages. The standard instructions should be about installing SDP in SKAO-managed clusters (STFC cloud, PSIs, ITFs) and treat Minikube as a special case (see next point). This can be found in the documentation here . The MR can be found at: https://gitlab.com/ska-telescope/sdp/ska-sdp-integration/-/merge_requests/234 Revise Minikube-related documentation to use standard  SKAO Minikube deployment  instead of custom configuration. See point 7. Design section is out of date. Components and Modules pages are missing information on queue connector Tango devices, data queues (Kafka) and QA components. The updated design section can be found here . The MR can be found at: https://gitlab.com/ska-telescope/sdp/ska-sdp-integration/-/merge_requests/237
    • 20.6
    • Stories Completed, Integrated, BDD Testing Passes (no errors), Outcomes Reviewed, NFRS met, Demonstrated, Satisfies Acceptance Criteria, Accepted by FO
    • PI24 - UNCOVERED

    • Low-G1 Mid-G1

    Description

      Address the specific points that have been raised from internal reviews of the documentation for recent versions of SDP (0.16.x):

      1. Poor introduction.
      2. Needs a list of functionality the system currently supports in a language that talks to the way others will use SDP.
      3. Needs an easy way to find the documented public API, e.g. where to find what it means when the SDP subarray reports its health state is OK.
      4. Missing easy to find documentation of SDP UIs (signal displays, Taranta dashboards). Needs to link to data product dashboard documentation.
      5. Not easy enough to find out how to use SDP for key use cases.
      6. Information is duplicated, e.g. instructions for operating the SDP in a number of pages in the "Running the SDP" and "Using the SDP" sections. Reorganise the pages to remove the duplication and inconsistencies as far as possible. Possible arrangement of sections:
        • Design
        • Installation
        • Operation
        • Development
        • Troubleshooting
      7. Information on installing and testing in Minikube is prominent in older pages. The standard instructions should be about installing SDP in SKAO-managed clusters (STFC cloud, PSIs, ITFs) and treat Minikube as a special case (see next point).
      8. Revise Minikube-related documentation to use standard SKAO Minikube deployment instead of custom configuration.
      9. Design section is out of date. Components and Modules pages are missing information on queue connector Tango devices, data queues (Kafka) and QA components.

      Who?

      • Solution and product managers.
      • AIV engineers.

      What?

      • Documentation revised to address points listed above.

      Why?

      • Make the documentation more useful to users not familiar with the system.

      References

      Attachments

        Issue Links

          Structure

            Activity

              People

                m.ashdown Ashdown, Mark
                m.ashdown Ashdown, Mark
                Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Feature Progress

                  Story Point Burn-up: (100.00%)

                  Feature Estimate: 2.0

                  IssuesStory Points
                  To Do00.0
                  In Progress   00.0
                  Complete2039.0
                  Total2039.0

                  Dates

                    Created:
                    Updated:
                    Resolved:

                    Structure Helper Panel