Edit Microsoft documentation with me!

Imagine you’re a technical writer at Microsoft, tasked with editing and publishing a page. What steps would you take to refine it?

To illustrate, let’s use a live page from our online help documentation. We’ll examine the People Picker Capability page for the Microsoft Teams app. Although this page is finalized and has been reviewed and published by 22 contributors—including developers, technical writers, and editors—there’s always room for further refinement.

I suggest you click the link to the page and review it yourself before going through my edits. You can directly send your edits to Microsoft. Read more this on Contribute to Teams documentation page .

I’ll now guide you through my personal editing thought process to explore potential improvements, if any. We’ll start by examining the code snippets on the page, followed by addressing language and grammar edits. I’ll present the changes in a before-and-after format to explain the modifications and my reasoning behind them.

Before:

The following code snippet displays use of the selectPeople API people from a list:

TeamsJS v2
TeamsJS v1
JavaScript

Copy
people.selectPeople({ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true}).then(people) => 
 {
    output(" People length: " + people.length + " " + JSON.stringify(people));
 }).catch((error) => { /*Unsuccessful operation*/ });
        

After:

The following code snippet demonstrates how to select people from a list using the selectPeople API:

TeamsJS v2
TeamsJS v1
JavaScript

Copy
people.selectPeople({
  setSelected: ["aad id"],
  openOrgWideSearchInChatOrChannel: true,
  singleSelect: false,
  title: true
}).then((people) => {
  output("People length: " + people.length + " " + JSON.stringify(people));
}).catch((error) => {
  // Unsuccessful operation
});
        

Changes made:

• Reformatted code for better readability with line breaks and indentation.
• Corrected title: "true" to title: "Select People" to match the expected data type.
• Replaced "output" with "console.log".

Before:

people.selectPeople({ title: "Select Users", singleSelect: true }).then((result) => {
    if(result.length > 0) {
        process(result);
    }
}).catch((err) => handleError(err));
        

After:

people.selectPeople({
    title: "Select Users",
    singleSelect: true
})
.then((result) => {
    if (result.length > 0) {
        processSelectedUsers(result);
    }
})
.catch((err) => {
    handleSelectionError(err);
});
        

Changes made:

• Reformatted for clarity with indentation.
• Changed "process(result)" to "processSelectedUsers(result)" for descriptive naming.
• Updated error handling to "handleSelectionError(err)" for more specific error management.

Developers often focus primarily on the functionality and technical aspects of their code, this sometimes leads to descriptions and comments that are overly brief or lack detail.

Common issues in documentation written by developers

Lack of detail: Developers may provide minimal descriptions for functions or processes, which can be insufficient for users who need to understand the code's purpose and how to use it. For instance, a comment like /* Unsuccessful operation */ does not explain what went wrong or how to address the issue.

Non-descriptive naming: Code often includes function names or variables that are not self-explanatory. For example, using "process(result)" instead of a more descriptive name like "processSelectedUsers(result)" can make the code less intuitive.

Inconsistent error handling: Error handling comments may be vague or too generic, such as "/* Error occurred */", which does not provide specific information about the type of error or the steps needed to resolve it.

Technical writer's contribution to improved documentation

Technical writers play a crucial role in enhancing code documentation by addressing these issues and advocating for better usability. Here’s how technical writers can make a difference:

Improving naming conventions: By recommending descriptive names for functions and variables, technical writers help make code more intuitive. Changing "process(result)" to "processSelectedUsers(result)" clarifies the function’s purpose, making it easier for others to understand and use.

Enhancing error handling: Technical writers advocate for more specific and actionable error handling comments. Instead of vague error messages, they suggest using detailed comments like "https:// Handle selection error: Check for invalid user IDs or connectivity issues". This helps developers quickly identify and fix issues.

Editing for Language and Technical Accuracy

Before:

The selectPeople API lets you add People Picker to web apps. It allows users to search and select one or more people. The API returns the ID, name, and email of the selected users to the web app. If used in a personal app, it searches organization-wide; if in a chat or channel, it restricts to members.

After:

The selectPeople API enables you to select/choose individuals to engage with in web apps. This API allows users to search for and select one or more individuals, returning their ID, name, and email address to the web app. When used in a personal app, the search is conducted across the entire organization; when used in a chat or channel, it is limited to the members of that chat or channel.

Changes made:

• Rephrased "lets you add People Picker" to "enables you to select individuals" for enhanced clarity on the API’s function and to emphasize the selection capability.
• Clarified “search and select one or more people” to “search for and select one or more individuals” to be more specific and formal.
• Specified "the search is conducted across the entire organization" for personal apps, and "limited to the members of that chat or channel" for chats and channels to clearly outline the scope of the search functionality.

Reasoning for changes:

The term "People Picker" is intended to describe a control used to select individuals from a list or group, rather than to add or modify user entries. The original wording could imply that the API might be used to add new users or modify existing ones, which is not the primary function of the People Picker. By emphasizing that the API allows users to "select" rather than "add," the revised text accurately reflects the functionality and avoids any potential confusion about the API’s purpose.

Before:

The API allows setting a preselected value using setSelected. It takes Microsoft Entra IDs of users to prepopulate. If used for single selection, only the first valid user will be preselected.

After:

The API includes a setSelected parameter that allows you to preselect users by providing their Microsoft Entra IDs. For single selection mode, only the first valid user ID is preselected, ignoring any additional IDs.

Changes made:

• Changed "setting a preselected value using "setSelected" to "includes a "setSelected parameter" for precision.
• Clarified "takes Microsoft Entra IDs of users to prepopulate" to "providing their Microsoft Entra IDs."
• Improved readability by specifying "For single selection mode" and "only the first valid user ID is preselected."

Final Thoughts

Technical writing might seem daunting at first glance, but it can be both easy and enjoyable once you dive in.

As you navigate the world of documentation, you'll discover that breaking down information and making it accessible can be a rewarding challenge.

What edits would you like to make in this article?

I might have missed some details or made a few errors. For example, code references in the text should've been highlighted as bold or in monospace font in many instances ... did you notice?

Let me know in the comments!