Before Canonical, I was an academic food scientist. I worked at a university, where I taught students, wrote scientific papers, and applied for research funding. I then transitioned into the software industry, taking a job as a technical author at Canonical.
I work on the Desktop team, where I lead documentation efforts for Ubuntu on WSL — the best way to set up an Ubuntu development environment on Windows, ADSys — which enables managing Ubuntu systems through Active Directory, and authd — for authenticating Ubuntu devices with cloud providers.
As a technical author at Canonical, I knew that I was expected to contribute to the design of the software, but I wasn’t sure how to begin contributing. If you want to become a technical author, or are an author curious about making design contributions, you might be interested in how I got started.
This is the first in a series of posts where I describe my experience contributing to design as a technical author.
Starting small
In my first few months at Canonical, engineers in my WSL team had a meeting with designers about the GUI of our new Ubuntu Pro for WSL application. I wasn’t in the original invite, so I asked to be invited. At that point, it probably wasn’t obvious to my team what I had to offer outside of documentation.
I had never worked with designers before, so I was a little cautious about stepping into their territory. I made some minor suggestions near the end of the meeting, partially to help improve the software but also to gauge the response of the designers. One of the designers thanked me for the suggestion and suggested that I make more. This helped me feel like my feedback was welcome, and immediately my design ambitions began to grow!
For example, we had one visual indicator in the GUI for two different events. I asked whether we could separate this into a pair of independent indicators. The designer said it was a good idea, tried the idea, and ultimately rejected the idea. Disaster?! Not really: designers try things, they experiment. This experiment didn’t work out as I had imagined, but it still led to an improvement: the indicator now included more descriptive text covering both events.
Approaching UX like a documentation problem
Perhaps unsurprisingly for a technical author, much of my design feedback has initially focused on the different varieties of text that are found in a user interface: labels, hints, placeholders, errors, logs, notifications, and more.
Shane made some great suggestions both on improving the documentation to make that behavior clearer and to improve the error message and log message shown in this case, which would help users/admins to figure out what needs to be done to allow the users to log in.
— example of engineering feedback on my suggestions to improve authd logs and errors
As much as anyone else at Canonical, technical authors think about text, and when I started contributing to user interfaces, I approached UX like a special kind of documentation problem.
There are — of course — important distinctions between writing docs and writing UX copy, but there are issues common to both. For example, an ambiguous instruction or notification can mislead users, whether appearing in the interface or the documentation.
Building on early success
When I was invited to be a reviewer for a PR related to changes in the GUI of Pro for WSL, it felt like a validation of my status as a legitimate design contributor. Like before, I focused mostly on the text, finding:
- Inconsistent use of placeholders: one field didn’t have placeholder text showing an example of valid input, while the other fields did.
- Misleading error messages: an error message prompted for an FQDN or hostname as valid entries, when an FQDN or IP address was needed.
- Contradictory information: hint text on a screen signaled both that a connection would be attempted and also that a connection would not be attempted.
- Unnecessary verbosity: explanation text for logs and errors was convoluted and difficult to read.
In a later PR review, I was still operating well within my comfort zone as a technical author, focusing largely on the clarity of text. Paraphrasing one of my comments:
The description “Register with your own server” should be updated to reflect that the user can opt to use the SaaS option without self-hosting their own server.
Thinking more about user flows
Eventually, I started to think more deeply about how users interact with the interface. I noticed some issues in the feedback users were getting from the interface, which could affect their understanding of the system and their ability to navigate the interface:
If the user enters
url-type-1, thefoofield is non-interactive with a default ofx.
If the user enters
url-type-2, thefoofield becomes interactive, but, when focused, the hint in the field is stillx, which is an invalid input for this type of url.
When a user switches to
not-url-type-2, any previously enteredfoobecomes fixed and grayed out. This may suggest that the previous entry is active (but uneditable). It should reflect the actual default value:x.
This marked the next stage in my development as a design contributor, where I wasn’t reviewing the interface as a mere container for static text, but as a dynamic user experience.
Conclusion
Engineers and designers value user feedback. As a technical author, you are a user of the product, and routinely test the software as part of your documentation work. Your feedback is valuable.
As a user, you are informed, with an awareness of the product vision and the technical discussions around realizing that vision. You are also skilled, in organizing and presenting information so that other users can achieve their goals with software. The feedback you give benefits from this understanding and skill-set.
If you don’t have experience in design, you will still need to start small, focusing on the areas where you can most obviously translate the skills that you have developed working on documentation.
In the next post in this series, I will offer some general tips for technical authors who want to start making their own contributions to design.
References and resources
- Vanilla framework’s guidelines for content, including UX copy
- Ubuntu project documentation on checking interfaces for accessibility
- Blog from Canonical technical author Erin Conley about the UX of documentation
- Blog from Canonical director of engineering Daniele Procida on the role of technical authors in design
Acknowledgements
Thanks to Carlos Nihelton (@cnihelton), Juan Ruitiña (@juanruitina), Robert Krátký (@rkratky), and Graham Morrison (@degville) for feedback on early drafts of this post.
