Hi all, this is Jeongil from the Technical Writing team in LINE. I am based in Korea, and have been in the field of Technical writing for the past ten years. Currently, my main job is writing and managing Clova (virtual AI assistant) documentation for third-party developers.
Perhaps this is the first time for you to hear of technical writing or may be you have heard about it but don’t exactly know what it is. In Korea, there is no degree programs for technical writing and in fact, it is quite difficult to find a person of this profession, especially the ones in the software industry, writing infrastructure documents or API references.
Having a rather small ecosystem, us technical writers in Korea rely much on web searches or team members for getting the latest news, tips, know-hows and strategies for technical writing. We struggle with such limited resources. Write the Docs Prague 2018 really hit the spot for me.
Introducing Write the Docs
Write the Docs (WTD) is a community for researching and sharing experiences on communication, documentation, and readers, and is specialized for the software industry. Annually, they hold two WTD conferences a year, in the spring and in the fall, in Portland, U.S, and in Prague, Czech Republic, respectively. The participants get to meet new people, engage in discussions, share their experiences on documentation and project management, and get the latest news. Have you by any chance read an article by Serizawa Susa, API the Docs Recap? API the Docs is a conference inspired by WTD.
The conference I attended was titled, Write the Docs Prague 2018, and as you can tell by the name, it was held in Prague, at Autoklub, for three days starting from September 9. The program of the conference consisted of the following:
- Writing day, Reception (September 9)
- Conference talk (September 10–11)
- Unconference and light talks
Here are some photos of the main hall and actual sessions.
Across the main hall was a place set for unconference where you could freely choose a topic from a board, as you can see below, and engage in a discussion about the topic.
Today, I’d like to share the two most memorable sessions with you.
Tackling technical debt in the docs
Louis Fahey, the speaker, works as technical writer at Sage in UK. She shared the concept of technical debt, and her experience in identifying and getting rid of technical debt.
The term, technical debt, is often used in software development, but in the session, Louise did not distinguish documentation projects from development projects for the term. She defined technical debt as an element that could incur cost due to temporary patches to solve issues quickly, instead of properly planning and revising issues for the long term. Louise quoted Ward Cunningham, one of the signatories of the Agile Manifesto, that technical debt describes “deferred, necessary work”.
Louise stated that technical debt is caused by a lack of skills and a lack of standards. The tools or technology used for documentation continuously evolves, and adapting the new ones into documentation projects can leave behind unnecessary content, images and style files. Lack of skills implies delays in the work process and struggles in document management due to such materials left behind. Lack of standard implies losing consistency or quality due to the absence of or outdated style guides/templates for composing or reviewing documents.
There are a number of ways to identify technical debt, and here a few of those she suggested to look out for, for documentation projects:
- Isn’t building documents becoming slower?
- Are there no content files, images or styles unused?
- Are there no broken links or bookmarks?
- Are there no issues that are unrelated to content translation in the process of localization?
She said that just like in software projects, if we ignore technical debt in documentation projects, the cost would inevitable rise, and consequently document quality will be reduced. To avoid such disaster, she recommended the following:
- Identify and list up technical debts.
- Categorize the technical debts identified.
- Determine the cost to resolve the debts.
- Prioritize the debts – (Is it urgent to be resolved? How important is it? How much do readers want the debt resolved?)
- Identify what you can gain from resolving the debt. (Prove that resolving the particular debt is necessary.)
- Spare time to resolve the debt.
- Measure and share the improvement after resolving the debt.
Suppose you have repeated these steps and finally became debt-free. However, to maintain such state, you have to continue doing the following tasks:
- Audit your project from time to time or periodically.
- Prepare a style guide or templates, and try to keep them up to date. (Resolving a lack of standards helps maintaining debt-free state.)
- Listen to the readers, get feedback, and reflect the ones you can apply.
- Define the Definition of Done. (DoD can be used to guarantee documentation quality.)
Once on our blog technical debt had been discussed, in Trustin’s post, Open-sourcing Armeria, which mentions “documentation debt”. Before I read his post, I thought the term was confined to the field of software. Seeing a session for it got me really interested, and gave me a whole new view on documentation projects. I got to learn that debt can exist as long as there is a process and cost for creating documents or content, and that you can apply software development methodology even on documentation — although the details may differ.
Now, being back at work, I’ve started paying off technical debt, by checking resources files in the Clova documentation repository, and writing up a script to eliminate unnecessary tasks for localization. I’ve been also restructuring information, setting up long term plans to make a style guide and templates, to keep the debt to the minimum.
Learning to love release notes
I believe developers will find this session helpful. Anne Edwards, a technical writer at Improbable, a start-up in UK presented a session on writing release notes.
She started the session by sharing her personal perspectives on release notes, and here they are:
- A list of bullet points published alongside a software release
- Consists of bug fixes, new features, and known issues
- Short and precise information
- Frantically pulled together at the last minute (Although this is her opinion, I couldn’t agree more)
Here are the components of release notes and her definitions:
- Bug fixes: Bugs or issues fixed that have been bugging users for a while
- Features: Additions of what users have been wanting for a while or have requested frequently
- Known issues: Errors or issues that are not frequent, or you do not know how to fix, or you plan to fix sometime soon
She shared her interview for her second technical writing job; she was asked what she did not enjoy about her then current job. Her instant reply was, “release notes”, for the following reasons:
- Release notes list elements that are not relevant to each other
- Release notes have a lot of context switching
- Release notes involve a lot of research for unfamiliar topics
- Release notes consist of short bullet points but require to provide enough context.
- Release notes are generally not fun to write as much as other documents.
Although she is not so fond of release notes, she grew to get some know-hows on writing release notes. First of all, she suggested to employ the expand out and simplify strategy. She mentioned that often if you try to write release notes simple, you end up missing out information or write something that is ambiguous. ‘Expanding out’ means, focusing on keeping information even though the outcome becomes long. ‘Simplify’ means, simplifying the the result of ‘expanding out’ by taking out less important information.
Secondly, she recommended to write in the user’s perspective. For example, if a module A is added to a system, we tend to write ‘Added a module, A, to the system’. If we rewrite this in the user’s point of view, we could write ‘You can now do XX (Module A)’. The difference comes from focusing on the user and the effects on the user’s workflow.
Lastly, she advised to refrain from using humor, idioms, and slang. If you write with too much of friendliness, you are likely to lose conciseness, resulting in making users work to get more information to understand what you are presenting in your release notes. Humor and idioms can cause misunderstanding by some readers. Also, such tone may not be the voice of your company or product.
The reason she recommends templates is to help both the writers of release notes and the readers, and here are the three templates she shared.
|You can now …||A pattern for bug fixes or features.|
|X now/no longer does Y when Z.||A pattern to compare the difference between before the release (Y) and after the release (X) and to provide context (Z)|
|X now/no longer does Y. This means you no longer /now need to do Z.||A pattern useful when guiding the goal (Z) by doing the current suggestion (X) than the past guide (Y). Also useful when guiding users to update their workflow. For example, having to do something extra or no longer having to do something.|
There was a lot of information in her session, and here are the key parts from her slides:
|Things to avoid||
|Tips for writing||
After her talk, I realized that I haven’t been writing good release notes myself. Her profound understanding of release notes inspired me so much, it got me to redefine release notes. I intend to apply her know-hows on our release notes, but with a slight modification; the patterns she provided may need to be altered to sound natural if translated in languages other than English. Other to-dos on my list are writing up a style guide and templates to keep technical debt to the minimum. 🙂
There were many other sessions to WTD which were extremely helpful in advancing my work, and I enjoyed numerous opportunities to share thoughts and experiences with other attendants. I thank LINE and my colleagues for letting me have this wonderful experience. I will surely make use of what I learned from the conference.
As I close my posting, I’d like to share one more thing; a tip maybe. Attending a reception event is really important. Most conferences are held in Europe or North America, and we tend to spend quite a time on traveling to the venue. You are most likely to arrive in the city of the conference on the start day or the day before. You would be exhausted from flying or riding and from jet lag, too, and would probably love to take a night off to get some sleep to be ready for the conference, making you skip pre-conference events. Well, at least this is how I and my colleagues tend to be in attending overseas conference.
This time, I somehow had a strong urge to attend the reception, and did attend, and was very much impressed. For three hours the day before the conference, I got to know and get acquainted with many people. I thank how the conference encouraged us to get to know each other. Thanks to the reception event, I was able to share and discuss what we learned from the sessions and our own experiences. This was nothing like any other conferences I’ve ever been to. Never had I a moment to feel lonely during meals and snack breaks. I’ve thought the awkwardness I’d felt in other conferences was due to a language barrier or different cultural background, but now I realize they were not the problem. If you are like me, try to attend pre-conference events like I did this time and get to know at least two to three people; believe me, your conference will turn out a whole lot different than the ones you’ve attended.