Thoughts on Grouper doc improvement from Emily Eisbruch as of Sept. 2023
Overview
Thanks to the community team working to improve Grouper documentation
Big Topics to consider
- Overall goals and scope of this documentation improvement project
- How to divide up and track the improvements
Questions
- Does the current Grouper documentation menu structure work well?
- What is the best way to solve the versions challenge (that sometimes users find a doc page and don't know if it applies to their version)
- On some pages we have notes at the top about the version, see example here
- For how many versions do we want to maintain doc?
- Is the Admin Guides menu structure effective ? https://spaces.at.internet2.edu/x/UAfw
- Is the horizontontal menu across the top of the Grouper wiki pages useful, does it have "the right" options?
Things to check when reviewing/improving Admin Guide wiki pages
- Is there an effective intro and overview at top of the page?
- Is the information current?
- Is the info clear and comprehensive?
- Is the version specified, if this info does not apply to all current versions?
- Are there links to other helpful pages?
- Is there a helpful See Also at the bottom of the page? Example here
Admin Guide Menu - Item to remember
If pages are added or moved in the Admin guide menu structure, to be at the level immediately under a top category, there is a manual step to remember.
The top level Admin Guide structure includes these big topics
- Release Info
- Installation and Configuration
- User Interfaces
- On-Going Administration
- Access Management
- Provisioning and Integration
- Utilities
- Glossary, Roadmap, and other
If a new page is created as a child page of any of these, remember to edit the Admin Guide page and add the new page, and its link, under the approporiate top catagory.
To clarify, if I create a new page directly under Utilities, for example, the new page won't automatically show up on the menu unless I manually add it and link it
from the menu under Utilities.