Chapter 8: Technical Analysis Templates

Knowing What To Include

When we create our technical documentation, we need to know which parts (articles, books, references etc.) make up the whole document. The first step is to determine what we are writing about. Then we need to determine who is the target audience. Once we have these two ideas defined, we can move towards creating an outline and gathering requirements.

Gather Requirements

Requirements gathering is the process of collecting, parsing, and organizing information into functional and non-functional components. We gather information from stakeholders who have an interest in the project.

A stakeholder can be anyone with an interest in the successful implementation of the project, including members of the leadership team, external teams, virtual teams, or colleagues who work alongside us. More often than not, there will be Project Managers or Technical Team Leads who own the project deliverables and communicate changes to the project timelines and deliverables.

Visual Aids

In the realm of complex designs and conceptual ideas, we should complement our explanations with illustrations, like drawings, to facilitate the readers’ comprehension of intricacies within a system. This practice is particularly common in web application architecture and database design mappings.

As technical analysts, our visual aids include screenshots, summaries of conversations with customers, the initial steps we take to resolve an issue, and any referenced documentation used during troubleshooting. These serve as our comprehensive knowledge base and should be self-sufficient, considering that we don’t know who will review them or where our audience might be located globally.

It’s crucial to include all the technical details necessary for our readers while avoiding unnecessary repetition.

Regional Teams

Working on international teams or addressing issues in various parts of the world may become a common scenario. The good news is that a computer in Africa is fundamentally the same as one in the United States (U.S.). Although the steps remain applicable, language barriers can be a challenge. What differs are the common words and shared understanding of technical conversations. Whether our support team is local or located in a different time zone, our notes should support them just as effectively. Clarity and conciseness are essential, along with providing accurate information to enable extended teams to address problems, regardless of their geographical location.

Problem Scope

When dealing with a specific issue, we must be cautious about scope creep, where a project’s goals start to expand beyond its original scope due to a poorly designed project plan. For example, if a customer calls for a password reset but begins asking about account name changes and account numbers, we need to redirect the conversation to our area of responsibility, which is password reset. Often, password resets don’t involve handling account details; this task may belong to a different team or department.

Many organizations have policies outlining the “least privileged access rule,” describing data governance and ownership with associated permissions. Following these guidelines, we handle the password reset and then transfer the call to the team responsible for account changes. In the context of software projects, scope creep can have similar characteristics, necessitating discussions with the project manager to address the issue effectively.

Business Case / Requirements

A business case or business requirements serve as tools for defining what the software should accomplish and the expected project outcomes once the system is designed. These requirements have been a recurring theme throughout this course, manifested in in-class activities and assignments. To consider a task completed, these requirements must be met. Typically, a project manager assigns tasks to the development team, and developers use tools like Jira (a project management application) to update task statuses (in progress, not started, completed).

In our role, we gather requirements from customers and company documents, piecing together a resolution. During calls, there’s no need to transcribe every word; we should only include relevant information necessary to solve the problem. Our operational knowledge of the system, combined with supporting documentation and caller-provided details, collectively form our notes and requirements.

User Persona

A persona represents our perception of a person’s character, their likely actions, thoughts, or feelings. Essentially, it’s an assumption or theory about what someone knows, based on data like surveys, questionnaires, or personal experience. In the role of a technical analyst, we can analyze the types of customers who typically call in.

This understanding helps us focus our attention when reading supporting documentation. It also allows us to build a core knowledge base, which is fundamental knowledge for gaining a deeper understanding of new topics. By concentrating on the top 13 or 15 call types, we can proactively research relevant documents and areas to handle calls more efficiently and effectively, reducing the need for extensive support from our team.