Details
-
Type:
Improvement
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: None
-
Labels:None
-
Story Points:1
-
Epic Link:
-
Sprint:TSSW Sprint - Jul 6 - Jul 20
-
Team:Telescope and Site
Description
Instead of providing contact information directly in the CSC documentation pages, at today's standup we agreed to instead link to the entry for the CSC in the HTML table generated from SALSubsystems.xml in ts_xml.
Please update the template accordingly.
I also have several requests for the buttons (which I can make a separate ticket if you prefer):
- Please order the buttons from "most needed" to "least needed", left to right. I realize it's a matter of opinion, but I suggest:
- "SAL Interface" (or "SAL API") to point to the ts_xml API page. I think this is clearly the most important button since anyone wanting to control the CSC or listen to output from it will need to know the details of the SAL interface.
- "github". This is the most important button for developers.
- "Jira". This is important for reporting issues. I could see arguments for putting it before "github", but I think it is common for advanced users to want to read a bit of code to see how something works.
- "Jenkins". I think this is clearly least important because most users will trust that the software builds correctly.
- Please consider removing the CSC name from the buttons. I feel this change would increase information density and reduce clutter and duplication. Also it makes the buttons a bit easier to read. I suggest using the "gray" color (I tried green, black, gray, and lightgray and found gray to be the most readable).
Finally, I suggest that the Version History link should be the last item in the main page, to make it easy to find. The main question any user is likely to ask when a new version comes out is "what changed?".
You can see what I have in mind here: https://ts-atdome.lsst.io/v/DM-25784/index.html
Regarding the contact link: if it's going to be a link to the SALSubsystems table then I wonder what to call it? "Contact" seems a bit too specific, since that table has additional useful information. I haven't thought of anything I really like. SALSubsystems seems too vague (it is only meaningful to T&S developers). Contact and Package Metadata seems clumsy. Package Metadata seems vague.
Should it be a section in the main page or just a button at the top? Those sections that are just a link (such as Developer Guide and Version History) are a hassle, though they appear to be necessary (I don't think it is possible to make an entry in the navigation bar at the left directly link to a different page, alas!). But I hate to add more such sections unless we really need them. So in this case perhaps a button would be better?