Documenting Our Work

Documentation is part of the work.

ISS depends on shared knowledge to provide reliable services, support customers, coordinate projects, recover from incidents, maintain systems, and allow employees to back one another up.

Important information should not exist only in someone's memory, email, Microsoft Teams messages, telephone conversations, or hallway conversations.

The ISS Communications Standard establishes the expectation that work is documented in tickets or appropriate project artifacts and that work handed to another employee includes enough information for that person to continue.

Why Documentation Matters

Good documentation helps ISS:

• Avoid repeating work.
• Reduce dependence on individual employees.
• Enable the community to use self-service resources.
• Support customers more consistently.
• Transfer work between employees and teams.
• Troubleshoot recurring problems.
• Maintain systems safely.
• Train Technical Leads and Backups.
• Understand previous decisions.
• Recover services more effectively.
• Improve services over time.

Documentation is especially important when work affects a service that someone else may eventually need to support.

A useful standard is simple:

Could another qualified ISS employee understand what happened and continue the work without starting over?

If the answer is no, more documentation is probably needed.

Document in the Right Place

Different kinds of information belong in different systems.

KACE

KACE is the operational record for service requests, incidents, and routine ticket-based work.

Tickets should contain information such as:

• What the customer requested or reported.
• Relevant troubleshooting.
• Findings.
• Actions taken.
• Customer communication.
• Vendor interaction.
• Changes made.
• Decisions affecting the request.
• Work remaining.
• Dependencies or delays.
• Next steps.
• Final resolution.

Ticket documentation should allow another employee to understand the current state of the work.

Project Artifacts

Project work should be documented in the project's working artifacts.

Depending on the size and formality of the project, these may include:

• Project plans
• Requirements
• Milestones
• Assignments
• Due dates
• Communication plans
• Testing information
• Traceability
• Deployment plans
• Go-Live Checklists
• Training materials
• Lessons learned

Project documentation should follow the level of rigor established for the project.

IT Hub

IT Hub is the primary location for reusable ISS knowledge.

Information that employees or customers are likely to need again should generally become an appropriate IT Hub article rather than remain buried inside an old ticket, email, Teams conversation, or project file.

Examples include:

• Operating procedures
• Troubleshooting procedures
• Support instructions
• Standards
• How-to articles
• Service information
• Customer instructions
• Technical procedures
• Frequently needed reference information

Detailed expectations for IT Hub are addressed in Knowledge Management and IT Hub.

SharePoint and File-Based Artifacts

Some information is better maintained as a file rather than an IT Hub article.

SharePoint may be appropriate for working files and artifacts such as:

• Spreadsheets
• Project files
• Diagrams
• Source documents
• Vendor documents
• Reports
• Large technical files
• Other files that do not translate well into a knowledge article

Whenever practical, IT Hub should point employees to the authoritative file rather than requiring people to know where to search for it.

Communication Is Not Documentation

Email and Microsoft Teams are useful communication tools.

They are not automatically the authoritative record of the work.

When a conversation results in an important:

• Decision
• Requirement
• Customer commitment
• Troubleshooting discovery
• Change in direction
• Assignment
• Resolution
• Technical discovery

that information should be placed in the appropriate ticket, project artifact, IT Hub article, or other authoritative record.

The goal is not to copy every conversation.

The goal is to preserve information that someone will need later.

Document Decisions, Not Just Actions

Documentation should explain meaningful decisions when the reason may not be obvious later.

For example, knowing that a configuration was changed can be useful.

Knowing why the configuration was changed, what problem it addressed, and what alternatives were considered may be far more useful six months later.

Good documentation preserves enough context to keep future employees from having to rediscover the same information.

Document the Handoff

Work frequently moves between employees or teams.

A handoff should include enough information to answer:

• What is the issue or request?
• What has already been done?
• What was discovered?
• Why is the work being transferred?
• What needs to happen next?
• Are there deadlines or commitments?
• Is anyone waiting for an update?

Changing the owner of a ticket is not, by itself, an adequate handoff.

Documentation Should Be Proportionate

Not every activity requires the same amount of documentation.

A simple password-reset ticket requires much less documentation than a major system migration.

Employees should use judgment based on:

• Complexity
• Risk
• Service impact
• Likelihood that the work will recur
• Number of people involved
• Future support needs
• Value of the information to others

The objective is useful documentation, not documentation for its own sake.

Protect Sensitive Information

Documentation must not become a place to store information that should be protected elsewhere.

Personal passwords should never be documented or shared.

Shared or system-level credentials must be handled through the approved ISS Password Push processes rather than being placed in:

• Tickets
• IT Hub articles
• Email
• Teams
• Project documentation
• Other normal documentation systems

Access to sensitive technical documentation should be limited appropriately.

Documentation Is Part of Completion

Work is not necessarily complete when the technical task is finished.

When documentation is necessary to operate, support, maintain, or understand the work, completing that documentation is part of completing the work.

This is especially important for:

• Projects
• New services
• Significant changes
• New service offerings
• Complex troubleshooting
• Recurring support issues
• Maintenance procedures

Connection to Our Values

Communication Matters because documentation allows information to survive beyond a conversation.

Integrity Matters because our records should accurately reflect what we did, why we did it, and what remains.

Excellence Matters because good documentation allows ISS to support technology consistently rather than depending on memory or individual employees.

People Matter because good documentation allows someone else to help the customer even when the person who originally performed the work is unavailable.