Body
This is for information about procedures and instructions intended for ITS-only use. Specific to all staff and students within ITS.
Based on our ITS Guiding Principle: Prioritize simplicity, optimal use, and comprehensive documentation this knowledge base proves the preferred methods for documentation at this time within ITS. Comprehensive documentation is a priority, given our limited resources, to establish standardization and knowledge share across the team. It provides transparency and cross-functional team support when needed. We encourage all in ITS to incorporate documentation time into their projects and tasks!
Primary Documentation Platforms
At this time, ITS has two main documentation platforms to utilize for the majority of our work and it is recommended to start with these as centralized repositories first.
Tommie Tech Services - Knowledge Base
The Tommie Tech Services Knowledge Base has a variety of public and private folders to create and update documentation for our community.
- Use For: Widely accessible general documentation that is not directly tied to a data source.
- Access: All at the University can access the Knowledge Base via Single Sign On (SSO). Any employee in ITS can create, update, or comment on a Knowledge Base Article.
- Additional Training:
- Examples include:
- How to use a tool, system, or platform - internal and external
- How to complete an operational or business process which does not incorporate data
- Recommended troubleshooting for errors
- Standard operating procedures
- Frequently asked questions - internal and external
- Processes to empower self-serving solutioning and learning.
- ITS Standards and Guidelines
- How to request access to a platform, tool, system
- ITS Internal Specific Documentation Folders: any private internal articles for ITS teams can be stored in the appropriate folder here.
Data Cookbook
The St. Thomas Data Cookbook is our enterprise data catalog where all of our data is defined, metadata is transparent, systems are documented, and outputs are documented for transparency.
- Use For: Widely accessible documentation that is directly tied to a data source.
- Access: All at the University can access the Data Cookbook via SSO and create or update data definitions. Elevated capabilities are necessary to add or update specifications.
- Additional Training:
- Examples include:
- Data Definitions (Technical & Business)
- Description & Logic of Reports, Dashboards, Charts, Tables for users - internal ITS and external
- How data is used in a process
- Storing coding scripts and notes about them: Appworx, SQL, PSQL, Python
- APIs utilized and/or ELT scripts
- Flowcharts of any data flow/process across systems
- Any metadata for any system, tool, or platform we have
- New Fields, Changes to Fields, Removal of Fields
- Data that is shared with any tool or system.
Secondary Documentation Platforms
If the first two platforms Tommie Tech Services - Knowledge Base and/or Data Cookbook do not fit the needs, below are secondary platforms to utilize until the first two become applicable. As we continue to identify centralized secondary documentation platforms used within ITS, we will update this article.
Jira - Project Based
For ITS Project specific notes and documentation Jira may be where this information is held. Once final process and/or documentation is ready for a broader audience you can migrate it to Tommie Tech Services - Knowledge Base and/or Data Cookbook.
Microsoft Teams - Project Based
For ITS Project specific notes and documentation Microsoft Teams may be where this information is held. Once final process and/or documentation is ready for a broader audience you can migrate it to Tommie Tech Services - Knowledge Base and/or Data Cookbook.
OneStThomas Intranet
For any specific information that would not be captured in the primary platforms above and needs to be visible to our internal community, OneStThomas is the place. Whether it is on the ITS OneStThomas page, a team-specific OnestThomas page, or in a news article.
ITS Team SharePoint Site
For any specific outputs including row-level data, compliance, or sensitive information specific to the business needs of an ITS team, this informaiton should be stored within your ITS Team SharePoint Site. The access to this SharePoint site should be limited and standards set within the individual teams.
Tommie Tech Services - Ticketing
For any notes or documentation specific to the ticketing aspect of Tommie Tech Services will live within the ticket itself. If any information from the ticket could be elevated to a troubleshooting article, How-To article, or data definitions please update the appropriate primary documentation platform.
Twiki - Server Documentation
We have utilized Twiki for ~15 years to for server specific documentation, including upgrade information, access, owner, and overview. Special access is required to view this documentation and is based on functional team responsibilities.
What if I think it should go in multiple documentation platforms?
Data Cookbook & Knowledge Base
- Create the necessary information in the Data Cookbook first.
- Write the Knowledge Base Article second, and link to the necessary Data Cookbook items you created in step 1.
Based on our data, more visit the Knowledge Base first before the Data Cookbook therefore linking to the Data Cookbook from the Knowledge Base is best.
Primary Platform & Secondary Platform
- Migrate anything that is finalized from the secondary platform to the primary platform first.
- Any additional documentation left in the secondary platform that is not moving to the primary platform should be noted in the primary platform, ideally with a hyperlink on where to find it. A goal to show the path for more information.
Related Articles