Documentation Standards

Owned by Elizabeth Storrs
Last updated: Dec 20, 2024
4 min read

Meeting Notes

Templates for Documentation Pages & Sub-Pages

  • When starting work on a new bug or request, create a child page under the Bug Documentation or Requested Updates/Development Documentation “parent” pages. In the new page, select the correct template and fill in the table at the top. Continue to add notes and other documentation underneath the table.

    • Both the Request Documentation and Bug Documentation templates have built-in tags and page properties that drive the tables on each “parent” page.

    • Make sure to “publish” the page and don’t leave it as a draft, as it will not appear in the table.

  • in order to update a page that was created before 2/22/2024

    • Open one of the pages that already has the page properties embedded and copy the table

    • open the page you want to fix in edit mode

    • at the top (or somewhere, technically doesn't happen to be at the top) type /page properties to get the widget thing

    • paste the table into the widget [note that depending on what you get when you copy the table, you may be able to paste the page properties widget itself and skip these two steps].

    • edit the table column with that project's details, but don't change the left-hand column (that's where the headers for the summary macro come from)

    • save/publish the new version of the page

    • add a label to the page for either slate-bug or slate-request

      image-20240312-150349.png

       

The third type of ‘work to be done’ pages are the Cycle Prep. Currently there are no templates for this, but that could always change!

Labels

In addition to the -bug and -request labels mentioned above:

watch-for-updates (and the recycling icon) is used for items where there is not a nice/elegant solution that completely meets our needs when it first came up, but it seems likely that there could be future development by Slate that might provide a better solution. This way the item can be closed while we wait without losing it entirely

Status codes: (/status)

  • green = COMPLETE

  • yellow = ON HOLD (not being actively worked on, but not closed out yet)

  • red =  IN PROGRESS (actively being worked on)

  • blue = PENDING (has not been started yet, but is in a trajectory to be worked on)

  • purple = WAITING (some external trigger, such as a particular date or condition, needs to be in place before this can move to another status

  • grey = CLOSED (abandoned without completing, and no future intention of completing)

Close project/Archive old pages

  • Once the page for a project (either bug or request) is complete or closed, it should be moved to the (Closed) version of the parent page.

    • You can either drag and drop from the side-bar content menu or use the tool within the page to “Move” it.

    • After it is moved so that it is no longer a “child” page of the main “parent” page, it will no longer be listed in the page properties report in the (Closed) “parent” page.

Denodo Queries

  • All queries connected to Denodo should be put in the “Admin: TTS” custom permission to prevent non-TTS personnel from finding/editing.

  • All queries connected to Denodo should be put in the “TTS - Admin” realm.

  • All queries connected to Denodo should have one of the following statuses added to the query name:

    • DRAFT - Under construction, actively being modified and updated for future testing/development and migration to production.

    • DEVELOPMENT - Query is connected to Denodo development environment and is actively being tested by “external” users (such as UCM, Finance, etc.). Modifications may be made based on testing outcomes, and query is not yet final.

    • PRODUCTION - Query is actively in use and connected to Denodo production environment, should not be edited or updated without working with the DSE team.

  • All queries connected to Denodo should have a version number. Future iterations should be updated so the version number is the previous version + 1. (e.g., PRODUCTION v1 > DRAFT v2 > DEVELOPMENT v2 > PRODUCTION v2)

Definitions of Projects, Cyclical Tasks, and Issues

(Stolen from SHK’s Project Request Process guide)

Project:  Projects are ventures initiated to address a particular need, help fulfill a goal or take advantage of a new opportunity and are managed in a systematic way to achieve the desired outcome. They can be an individual or collaborative effort and usually involve a series of coordinated activities, tasks, and milestones. Successful projects are guided by a project plan that outlines the objectives, scope, resources required and expected outcomes of the proposed project.  There should be a stakeholder available for decision-making purposes and can be managed by a team or project manager.

Cyclical Task: Cyclical tasks are recurring activities that are conducted throughout the year at different points within the organizational workflow. These tasks typically follow a predetermined schedule or pattern and may involve repetitive actions such as application launches, monthly reporting, targeted marketing campaigns, quarterly reviews, or decision releases. They often require careful planning and coordination to ensure that they are completed consistently and efficiently.

Issue/Quick Update: Issues refer to any challenges, roadblocks, or problems encountered while working on a project, or in everyday work, that can either be addressed quickly or need to be addressed quickly. Issues need to be identified, tracked, and resolved promptly to ensure the smooth progress of a project, address customer service complaints, or assist in the continuation of day-to-day operations. These can also involve dealing with outside vendors and submitting support tickets.