Ubuntu Wiki

Purpose

Outline a writing process to ensure effective and useful documentation contributions.

Intended Audience

Primarily focused on new contributors, but this information is useful to everyone on the team.

Proposed Outline

1. Overview
2. Define the Goal of the Document (1 sentence)
3. Define Use Cases (1 sentence each)
4. Define the Audience (Personas)
5. Research Common Issues and Questions (Ubuntu Forums)
6. Outline
7. Submit to Doc Team
8. When to Begin Writing

Session Content

1. Overview 2. Define the Goal of the Document 3. Define Use Cases 4. Define the Audience 5. Research Common Issues and Questions 6. Propose an Outline 7. Submit to Doc Team 8. When to Begin Writing

The purpose of this session is to review the steps contributors should take when preparing documentation.

By taking preliminary steps to plan and structure documentation before any writing begins, the documentation will be more effective, better organized, and ultimately, more useful.

This session will follow this agenda: (paste agenda)

Overview

The reason I proposed this session is that many new contributors seem to face similar challenges when preparing new documentation.

I also felt it might be helpful for veteran documentation team members looking to improve their writing.

This preparation process is not only important to focus your writing, but also clarifies your task to the rest of the team.

For instance, if you are writing documentation for novice users of an application, providing that information up front will ensure you get relevant questions and feedback.

Not communicating the scope of your documentation up front may produce feedback that isn't relevant to your task and can create a frustrating experience for the team.

Remember that when you contribute to Ubuntu Documentation, you're not working in isolation. You are part of a team!

The methods discussed in this session do not need to be performed in any particular order. You can use one or two of these methods, or all of them if you like. Ultimately it depends on what is useful for your documentation.

If something is helpful, then use it. If it's tedious, confusing, and doesn't add anything to the quality of your documentation, then don't use it.

Define the Goal of the Document

Prior to writing any documentation, you should think about who you are writing the document for and what purpose it serves.

Software Engineering and Usability both provide processes that we can borrow from for writing documentation.

Software Engineering defines an Objective during the planning phase of an application. Engineers need to clearly understand the purpose of what they are developing.

In Documentation, we can also define an Objective or Goal for our document.

Defining a goal gives you a reference point when writing your documentation. When considering whether to include something or when determining how to word or structure something, ask yourself how it fits with the goal you've defined for your documentation.

Defining a goal also clarifies the scope and direction of your documentation for the rest of the team.

For example, the goal of documentation for the Make A USB Startup Disk application is: "Instruct a novice user to make a bootable USB drive (LiveUSB)."

The goal of documentation for the Ubuntu Packaging Guide is "Provide a comprehensive reference of packaging tools and methods for novice users, expert users, and developers"

Your goal should be very general and describe the scope of your documentation in terms of the bigger picture.

Define Use Cases

In Software Engineering, prior to developing an application, developers define use cases to outline the different functions their application will serve.

A use case is a task for which someone will use the software.

To define a list of use cases, ask yourself, what will someone want to do with this software?

You can create a list of use cases by playing around with the application, working with the developer or development team, or by reviewing existing documentation.

Use cases can be as simple as "Edit database record" or as complex as "Authenticate login details".

The wording isn't as important as identifying the task.

You can get as granular as you like when defining use cases. Make sure the use cases you define are in line with the goal you've specified.

Define the Audience

Usability Experts typically define generic user profiles to clarify what types of people will be using a software application.

A persona is a fictional profile meant to represent a typical set of users for the application.

This profile can be as detailed or as general as you like.

The point of a persona is to clarify your user audience and to provide a tool for you to put yourself in your readers' shoes.

By understanding the circumstances under which your reader will be accessing your documentation, you can provide more effective documentation that provides an overall positive experience for the end-user.

Think about how many times you've used documentation and felt frustrated because you couldn't find the answer to your question!

When preparing to write documentation, think about who will be using the application you are documenting.

What is their general computer skill level? Novice? Intermediate? Advanced?

What is their experience level with Ubuntu? Novice? Intermediate? Advanced?

Note that a user can be an advanced computer user but a novice to Ubuntu. Documentation for specialized networking applications might target this audience.

Typically you want to cater your documentation to the lowest skill level you've defined for your audience. You can create special sections on specific topics for advanced users.

Think about why someone would be using this application. User forums are great for getting this information.

What kind of application is this? Is it a general desktop application or is it a specialized application for developers?

Here is an example of personas I defined for the Ubuntu Packaging Guide. https://wiki.ubuntu.com/AugustinaBlair/PackagingGuidePersonas

You can find more information about Personas on Usability.gov, a website focused on usability run by the U.S. Government. http://www.usability.gov/methods/analyze_current/personas.html

Note that you don't have to have both use cases and personas defined for every document you write.

Some documents are general enough that focusing on tasks only is more appropriate.

An example of this is the Make USB Startup disk documentation.

It makes more sense for a document like this to focus on Use Cases and less on user profiles. The application is straightforward and regardless of the end-user's level of expertise, they will use the same information to perform the same tasks.

Other documents should cater more towards the types of users, especially if the tasks are widely varied.

An example of this is the Ubuntu Packaging Guide.

This is a very complicated document that covers a lot of different tasks. It makes more sense to define Personas and then define document sections to target those personas and what information they will need to perform typical tasks for their user profile.

Research Common Issues and Questions

Use the Ubuntu Forums to find out where current users have questions!

The forums are a great place to survey the landscape of what documentation is needed before writing a single word.

Here are some questions to get you started:

1. What are people using the application for? 2. Where are people experiencing the most confusion when using the application? 3. What are the most common questions about the application? 4. What are the skill levels (as far as you can tell) of the most vocal users? 5. What information would answer most of the questions on the forums?

1. A good example of this is minimum requirements for an installation.

Your goal in this research is to ensure your documentation answers the most common questions end-users have.

Users should be able to reply to common questions with a link to a section in your documentation.

Propose an Outline

This is the most essential method discussed in this session! If you don't use anything else I've discussed today, please use an Outline when creating your documentation.

Outlines allow you to organize content without getting weighed down by details.

Outlines are much easier for others to review than pages of text.

It is easier to see if something is missing in an outline.

It is also easier to rearrange items in an outline and see how they flow.

Remember that most users will not read your documentation from beginning to end. They will pick out the titles of sections that are most relevant to whatever they have questions about.

This is why understanding your audience and tasks is so important. When you know what information users are likely to need to look up quickly, it's easier to create sections that meet those needs.

The sections your documentation needs to contain will vary depending on the purpose of your documentation.

Generally, your documentation should contain an introductory section that explains what the application is in one or two sentences.

Your documentation should also contain an FAQ or troubleshooting section for addressing common problems.

Finally, your documentation should contain a link either to the project page for the application or to the Ubuntu forums for users who want more information than what is covered by the scope of your documentation.

If your topic is very complicated, your documentation should be grouped into sub-sections intended to address the different users.

For instance, the Packaging Guide contains a Basic section for new users and Advanced sections for users who have advanced or specific needs.

Remember to keep the documentation structure simple and easy to follow.

Again, readers will not read your document from beginning to end.

• Make sure you clearly define sections to help readers who are looking for specific answers.

Submit to Doc Team

I highly recommend you submit your documentation outline to the Doc team before you write a single word.

There is nothing worse than spending a lot of time on a section the team decides shouldn't be included in the final document.

Typically the folks reviewing your submission have a good understanding of how the documentation fits together as a whole.

Some topics in your outline might be better addressed in a section of the wiki whereas some are best suited for the system documentation.

The easiest way to submit your documentation is to create a sub-page in your own wiki name space on the Ubuntu wiki.

For instance, my wiki space is https://wiki.ubuntu.com/AugustinaBlair

I typically post drafts under my namespace as follows: AugustinaBlair/MyDraftDocument

Wikis make it easy for team members to make changes and leave comments. If you don't like the changes, you can roll them back.

The wiki is also web-based making it easier for folks on the team to access it wherever they are without downloading anything.

When to Begin Writing

Once you've gotten the ok on your outline from the team, you can start filling it out.

With all the previous research you've done, it should be really easy to fill in the remaining content!

That's all I have for discussing the pre-writing process. A discussion on the actual writing itself is best saved for another session, but I'll leave you with the following tips:

Feel free to disregard these suggestions in the name of clarity.

• The goal of any documentation is to benefit the reader so in any situation where these suggestions detract from that, go with what's best for the reader!

Avoid future tense! Ubuntu documentation is translated into a lot of languages and future tense is one of the most ambiguous to translate.

Avoid the passive voice! Not only is it annoying for translators but the passive voice also obscures clarity. Examples: Passive: The files are created in the home directory. Active: Application x creates the files in the home directory. Which one do you think is more useful to the reader?

Avoid extra words like "can" and "should". Examples: Don't: You can click on the button to open a new window. Do: Click on the button to open a new window. Don't: You should see the new window open on your screen. Do: When the new window opens, perform some task.

Use the imperative voice! Use simple sentences! I know this makes the writing sound boring, but it's a lot more useful than lengthy complicated sentences with "personality".

And Finally! Don't take criticism personally. Also, only consider the criticism that is relevant to your document.

Experienced team members will likely offer developmental advice or wording advice with usability in mind. Less experienced members are likely to dwell on spelling, word choice, or grammar suggestions. While you may take pride in your writing, consider that this isn't really *your* writing, it belongs to the community!

If you are disturbed by any feedback you get from anyone on the team, you should definitely discuss it with them privately. More than likely it's just the result of the limitations of text-only communication, and not anything personal

Ultimately, the best way to avoid confusion is to clarify the intent of your writing by using the methods I've discussed.

Examples discussed in this session: https://wiki.ubuntu.com/AugustinaBlair/MakeUsbStartupDraft

https://wiki.ubuntu.com/AugustinaBlair/PackagingGuidePersonas