Audience: There’s a whole world outside of IT 

Nordic Techkomm is the first tekom conference we’ve attended. tekom is the largest professional association for technical communication in Europe, and they hold several events throughout the year. Stockholm’s Nordic Techkomm was the earliest, so we jumped in. 

To our surprise, at least 50% of the ~200 attendees came from non-IT technical writing, like machinery and construction, electronics, and home appliances. In our software development bubble, we often forget that the world of technical documentation is much larger and includes people who describe physical objects. 

Trending topics

• Virtual/Augmented reality
• Voice search
• AI and ChatGPT
• Help bots
• Smart content reuse
• Content consistency and correctness 
• Corporate style guides
• Green Deal and product sustainability

Inspiring talks 💡

Fabrice Lacroix, Documentation on the Web

What are the specifics of online documentation we should address to create the best user experience? 

Our takeaways:

• Content structure and granularity: An inconsistent navigation experience and various topic sizes are documentation problems that are not handled well with analytics, user feedback, or searches. The answer to these problems is dynamic granularity – a must-have feature for any documentation site. 
• Content optimization: Why do we still have the navigation tree? Because of the lack of good searches. Generate pages based on searches, not vice versa. 
• User journey mapping: Deliver docs in the right context.
• UI customization: Engaging with the content is not possible with web docs. With paper docs, people can use sticky notes or write on the margins. Why don’t we give them similar tools? 
  

Olha Husarenko, Content structure and Documentation templates

Olha talked about content structure and templates. Templates are a technique we use and promote in our tool for technical writers, Writerside. It was great to listen to a like-minded colleague!

So, why structure? Why templates?

• The structure determines how we find, understand, use, and share information.
• Well-structured content is easy to find, read, and follow. It’s also easy to produce and maintain.
• To make content discoverable, make it logical for humans and readable for machines by  adding metadata, sitemaps, tags, and labels. 
• Check out Nielsen and Norman’s studies on how people read texts.
• Why are templates good for subject matter experts? They can focus on their expertise, get immediate guidance on structure, formatting, and writing style, and save time for review.
• For technical writers, templates remove barriers caused by writer’s block, help share knowledge among team members, save time for editing, and help other teams to create and maintain project documentation.
• With templates, it is easier to encourage developers to participate and contribute to docs. 
  

Dr. Oliver Friese, UX-driven improvement of the installation guide 

Taking a dishwasher to a UX lab was something we’d never seen before. Imagine half of your customers have problems with dishwasher installation. How do you learn what to improve in the instructions? 

• Set up a testing area in the lab.
• Record how users use the instructions to install the dishwasher. 
• Create a “heatmap” on paper instructions and locate problem areas.
• Run a workshop to brainstorm possible solutions.
• Select the best ideas using the dot-voting technique.

Use the results to drastically rework the installation instructions.

Jang Graat, Why the content review process is broken, and how to fix it

Modern content consists of many smaller reusable snippets. How can we build a content review process so that the reviewer sees the content as a whole, not piece by piece? How can we keep them from drowning in changes and commit messages? 

Jang’s idea is to let reviewers edit the compiled HTML page. Thus they will have the full context and no need to learn another review tool.

The concept seems very attractive, but let’s wait for an implementation to see if it applies to complicated review processes. 

Paula Stern, Lessons of a Documentation Project Gone Wrong

Here are some lessons learned from a project where documentation writing estimates were wrong by 6 times. As Paula put it, “A failed project isn’t a failed project at all if we learn something from it.” 👇

• Accept the insanity – anything could happen. 
• Do not sacrifice quality – good enough is not good enough.
• Trust writers in their estimations.
• Plan ahead regarding who will provide what information (and when), and who will answer questions. Ideally, the same person will do both. 
• Don’t forget to account for the work on extras like layout and the table of contents.
• Plan buffer time – you will need it.
• Have subject matter experts show you the project. Don’t document based on words alone!

The Future of Documentation – a workshop by Alina Terekhova, JetBrains

During the workshop, Alina presented an exciting challenge that had us all on the edge of our seats. She listed a few massive areas that could potentially impact the world of technical content and technology as a whole after listening to the talks and discussions on the first day. The areas were new technology, economics, health, law, and education. All are critical aspects of our lives and much bigger than producing technical content. 

She then gave each team the task of brainstorming ways in which tech writers could respond to these areas and how they influence us. It was a lively workshop that got us all fired up and ready to tackle whatever challenges the world of tech (and non-tech) throws our way.

The outcomes brought more questions than answers, but it’s a good start and solid ground for further experiments and research. 

• People are concerned about how to use the new LLMs to save time for more creative tasks and, simultaneously, how their focus might shift from creative work to producing structured machine-readable content.
• The future will bring more forms of technical content, including delivering instructions in Virtual/Augmented reality, conversational interfaces, video embeddings, gamification, and various new microlearning experiences. 
• Some classical practices and principles will stay, including content granularity and re-use, visual aids, “write less, say more”, reducing the “input-to-insight” time, and the need to involve documentarians in the development process as early as possible.

Conclusion

NORDIC TechKomm was a great event that brought us new perspectives and food for thought. There’s one more tekom conference on our list of tech writing events in 2023 – the tcworld conference in Stuttgart, on November 22-23. See you there! 

Come meet us, get a quick demo of our product, and discuss the latest developments in writing and publishing docs-as-code.

Here are the team’s plans for 2023 👇

1. NORDIC TechKomm, Stockholm, March 21–22

At this annual event with an independent nordic spirit, content authors gather to discuss modern trends, pain points, and hot topics in the field of technical communication.

On March 22 at 9:00 am, our colleague Alina Terekhova will host an interactive session to brainstorm about future trends in technical content delivery. Stop by to discuss what will shape the next 5–10 years in technical writing.

You’ll recognize us by our signature magenta T-shirts 😎

2. Write The Docs Portland, May 7–9

This is one of the largest conferences for documentarians held by the Write The Docs community. Writerside’s product lead, Anna Gasparyan, was there last year to give a talk about content reuse. This year we’re going to Portland with the JetBrains Grazie team to give you a comprehensive look at the natural language tools from JetBrains.

3. soap! Conference, Krakow, June 1–3

The focus for this small and cozy community event in the lovely city of Krakow this year is on content operations. We plan to hold an unconference session on documentation delivery, as well as publishing pitfalls and best practices.

4. API The Docs, Amsterdam, June 6–7

API documentation is one of our main targets this year, so we want to dive into the trends that are emerging in this area. Since part of our team is located in Amsterdam, this is an event we truly can’t miss. Meet our team at the talks and in the lobby to discuss all things related to API documentation.

5. WeAreDevelopers World Congress, Berlin, July 27–28

We believe that all members of development teams are writers. That’s why we will be attending one of the largest conferences for software engineers in Europe. Our plan is to show off the tool that helps entire teams write documentation without leaving their favorite IDE.

6. LavaCon, San Diego, October 14–17

We’re thrilled to have our own booth at this legendary content strategy conference. LavaCon is one of the premier events for technical writers and content strategists. Let’s meet up there!

7. tcworld, Stuttgart, November 14–16

We wouldn’t miss the tekom association’s oldest and most well-respected conference. We invite you to stop by our booth to get a quick demo session of the writing tools from JetBrains. We can chat about things like content reuse and profiling, documentation versioning with Git, and how to approach docs-as-code without fear.

Do you have any recommendations for conferences and events we should attend next year? Are there any fantastic (tech) writing events that we’re missing in 2023?

Share them in the comments below 🤓 👇

The more we work on a tool, the more intuitive and easy to use it seems. This is why documentation is sometimes postponed to the last minute, or even scrapped completely. Customers are left to figure out for themselves what the tool can do.

However, documentation benefits even a small team, especially at an early stage of a product’s development.

• Documentation helps to flatten the learning curve. Fewer users will drop off because they fail to find a feature. 
• It takes the burden off support, which is a big advantage for a small team.
• Online documentation improves content marketing and SEO. 

• Documentation is a sign of consideration and appreciation of the user. It also indicates a sense of reliability that helps build trust in the product.
  

Plugin developers can publish documentation directly to the JetBrains Marketplace. That documentation is not limited to a single page with regular text – you can also publish structured guides, complete with navigation and search.

Check out these examples:

• Grazie Professional Documentation
• Docs for JetBrains Academy   
• Rust Documentation 

How do you create such documentation for your plugin?

First of all, it’s important to define the minimum scope of your documentation.

Your users probably don’t need a full reference or UI guide, especially if you follow the IntelliJ Platform UX and UI guidelines.

They need to understand basic scenarios and how exactly your plugin makes their lives better.

What your users need is a jump-start:

• Overview or introduction: Briefly cover the plugin’s core features and benefits.
• Quick start: Step-by-step instructions on how to install and configure the plugin, its dependencies, or its prerequisites. Describe a simple scenario that demonstrates how to use the plugin. 
• Known issues or troubleshooting: Include a detailed list of all known issues and their solutions, best practices, and workarounds. Don’t forget to tell users how to collect debug information if something goes wrong.
  

Now, how do you start writing? And how will you publish what you’ve written?

Well, we have a tool for that.

JetBrains is working on its own solution for writing documentation – Writerside. You can use its Early Access Program version to write and publish documentation for your plugin, right inside your favorite JetBrains IDE.

Would you like to try it out?

1) Download the Writerside plugin on JetBrains Marketplace.

2) Create a documentation project or module in your dev project.

3) Select a template for one of the 4 main documentation types: How-to, Reference, Overview, or Tutorial. We provide the structure, and you fill it in with content.

4) Write in Markdown, inject XML elements, such as tabs, complex tables, collapsible elements, and more.

5) Publish on JetBrains Marketplace with the help of the Writerside team. The publishing process itself is not automated yet, so you’ll currently need to build your docs locally and send us the .zip archive. Here are detailed instructions on how to do that. We’ll take care of the CI/CD configurations and actual publishing.

6) Join our Slack channel for support, news, and updates. Although we assume you’ve read and agreed to it before joining, please don’t forget to review our Code of Conduct. 

See you on the writer’s side! 🤓

• Maintain consistency throughout your documentation in terms of style, terminology, the level of detail, and so on. 
• Avoid making multiple updates when a user interface or a workflow changes.
• Reduce the review and editing effort.
• Reduce the localization costs.
• Automate the routine – reproducing the same pieces of content repeatedly adds mundane work and duplicates your efforts. 

While we don’t argue with the benefits of single-source publishing, in this post we would like to draw your attention to its pitfalls so that you are forewarned and can reuse content wisely. 

At JetBrains, we reuse content a lot. If you are familiar with our IDEs, you’ll know that they are built on top of the IntelliJ platform, meaning there is a lot of shared content that goes into multiple documentation instances under different filters and conditions. 

Here’s a simplified scheme to give you an idea of how entire articles and smaller chunks of content are reused between different documentation instances:

We have 21 online help instances built from the same set of source files, and about two dozen tech writers contribute to this project, so we know single-source inside and out and have fallen into every one of its traps before. 

In this post, we’ll look at a few of these traps, which I’ve dubbed as follows:

• Abuse of reuse
• Source code reduction
• Misuse of reuse
• Traffic cannibalization

1. Abuse of reuse

Tools powered with single-source features allow you to include reused content under conditions and filters, thus giving you a lot of flexibility. Sometimes too much flexibility, really. 

Let’s look at an example of content reuse with conditions where filters are justified. Here, filters are used because programming languages have different components. For example, in Java you would search for usages of a method, while in C++ this would be called a function, and in database tools you would search for usages of a table, column, or key. 

So filters here are legitimate.

<tip-of-the-day id="FindUsages"> 
<p>
    You can view the list of all usages of a 
    <for product="ij,py,ws,ps,rm">method</for>
    <for product="cl">function</for> 
    <for product="db">table, column, or key</for> 
    across the whole project, and quickly navigate to the selected item. 
</p>
</tip-of-the-day>

Now let’s look at another example: 

<tip-of-the-day id="ChangeSorting" product="ij,py,ws">
    <p product="ij">
        You can sort completion suggestions by relevance
        or alphabetically.
    </p>
    <p product="py">
        By default, completion suggestions are sorted by relevance, 
        but you can sort them alphabetically bу selecting the 
        <control>Sort by Name</control> option.
    </p>
    <p product="ws">
        To choose how you want to sort completion suggestions - by name
        or relevance - toggle the <control>Sort by Name</control> checkbox.
    </p>
</tip-of-the-day>

Can you guess what’s wrong here? All three paragraphs here are about exactly the same thing. The only thing different is the wording and the level of detail. Nothing is actually reused here at all apart from the title.

🪴 Root cause

There are a few reasons why things like this happen:

• Writers think they can come up with better wording than the original piece, but they don’t feel comfortable replacing their peer’s work with their variant. 
• Writers are affected by feedback from a user who’s not satisfied with the level of detail, and add redundant information as a reaction to feedback.

⚖️ Weigh the gains against losses

Do you remember the reasons to bother about reuse? Let’s weigh them against this example:

💡 How to avoid

Here are some strategies that we have implemented in our writers’ team to help us prevent things like this from happening:

• We’ve developed an in-house style guide. In many cases, it helps us avoid abuse of reuse, as there’s an agreement on how much detail to provide, the tone of voice, and so on, so that these things are not a matter of a writer’s personal taste.
• We’ve automated checks against our style conventions so that style violations are highlighted in the editor and the author is prompted to rephrase. There are different ways to implement such checks depending on the editor you use. If you are using a JetBrains IDE, you may want to check out the Grazie Professional plugin that supports Vale syntax and has built-in checks against some popular style guides. 
• In our team, we have agreed on the “improve for yourself – improve for everyone” principle. You don’t need to be shy about improving a piece of text for everyone instead of multiplying similar chunks.
• We are also working on implementing a syntax checker that would detect non-exact duplicates and suggest extracting them to a library so that they can be reused. We already have an MVP of this linter ready to use, but we are also looking at different approaches that might involve technologies like ElasticSearch, machine learning, and others.  

2. Source code reduction

Sometimes you want to edit a page and open the source file, and what you see is just a couple of lines behind a web page that’s several screens long. Instead of being able to easily locate the piece you want to update, you find multiple includes wrapped into one another with filters and variables declared God-knows-where, and it takes you a while to figure out what the text you see on a web page actually resulted from. 

Here’s an example of such code reduction from my recent talk at Write the Docs Portland conference:

🪴 Root cause

Since our company makes developer tools, we as writers work closely with developers and write for developers. We often tend to adopt developer approaches, and we even author docs in an IDE. So we sometimes get carried away with the beauty and brevity of source code reduced to a single line that lets you unveil layers of content behind it like a nesting doll.

⚖️ Weigh the gains against losses

Now let’s look back at our benefits list and test this example against them.

💡 How to avoid

Honestly, this is not something that we at JetBrains are champions at, but as a team, you need to find a balance between reusing everything that could possibly be reused and keeping your code readable and searchable. We suggest you try sticking to the following principle:
Just because you can doesn’t mean you should.

Sometimes it’s better to choose some duplication over the wrong abstraction and put up with less than 100% reuse. Otherwise you may complicate your life by creating source code that is rigid and difficult to maintain and reuse. And the investment you’ve made into reducing it can never be recovered.

3. Misuse of reuse

Sometimes, you realize you’ve been writing the same phrase (like a path to a settings page) several times a week. It’s only natural to be tempted into thinking that if you are repeating yourself so often, you must be doing something wrong and it makes sense to reuse it. 

Here’s a procedure that tells you how to configure something in an IDE.

Let’s look at the source code behind the first step:

<include src="PREF_CHUNKS.xml" include-id="step_open_settings_page">
    <var name="page_path" 
         value="Build, Execution, Deployment | %language% Profiler"/>
</include>

<chunk id="step_open_settings_page">
    <step>
        <include src="PREF_CHUNKS.hml" include-ide="open_settings_page"/>
    </step>
</chunk>

<chunk id="open_settings_page">
    Press <shortcut key="ShowSettings"/> to open the IDE settings and select 
    <control>%page_path%</control>.
</chunk>

To reuse everything that can potentially be reused here, you need to introduce variables and wrap reusable snippets into one another. So, in the end, there are 10 lines of code behind this little sentence. And I’m asking myself – is it really worth it?

🪴 Root cause

In software development, there’s a principle called “DRY”. It was formulated as early as 1999 in a book called “The pragmatic Programmer”. “DRY” here stands for “Don’t Repeat Yourself” and it’s aimed at reducing repetition of software patterns and replacing it with abstractions to avoid redundancy.

Just like in programming, this principle is often misunderstood by technical writers who are tempted to re-use anything that could potentially be reused and wrap multiple reusable snippets into one another, thus creating complex markup structures where changing one element breaks the logic for other dependent elements.

⚖️ Weigh the gains against losses

💡 How to avoid

What can we do about it? 

• Remember that the “DRY” principle doesn’t always work. If you strive to achieve perfect reuse, you may end up implementing a tangled ball of dependencies and it will be very difficult for your teammates to understand and maintain the code. 
• Wikipedia tells you that the opposite of the “DRY” principle is the “WET” principle, which stands for “Write Every Time” or “We Enjoy Typing” or even “Waste Everyone’s Time”. However, I would suggest that the opposite should be the “KISS” principle introduced in the 1960s in the US navy that stands for “Keep it Simple, Stupid”. This states that most systems work best if they are kept simple rather than made complicated. 
• Think of other means to achieve your goal. In this example, the ultimate goal of the author was to automate the routine task of typing the same phrase. Just like in a programming language, there are usually multiple ways to achieve the same goal. In this case, you could create a template or a completion pattern and assign a hot-key combination to it so that you can paste the required text with a couple of keystrokes. 

Wouldn’t that be easier for everyone?

4. Traffic cannibalization

In the previous four sections, we talked about the pits that content authors may fall into if they don’t weigh the gains of content reuse against possible losses. This one affects our customers – the people who read technical documentation.

Web content cannibalization happens when you pull your audience in more than one direction. 

That’s exactly what happens when you reuse content and publish identical chunks of it to multiple outputs on the web. Search engines like Google just ignore some of the web pages because identical content already exists on a different page and it’s ranked higher in search results.

This is an example of a search query.

The top ranked result is the relevant article that talks about multiple cursors, only in JetBrains Rider – a different JetBrains product – and not IntelliJ IDEA. 

The content of this article is single-sourced and, for some reason, Google thinks that the page from Rider documentation is more relevant.

🪴 Root cause

Our SEO specialists have helped us identify some of the reasons for this problem (though the list may be incomplete):

• If content is published earlier, it’s indexed earlier. So if JetBrains Rider is released several weeks before IntelliJ IDEA, chances are that Google crawlers will have already indexed this article before IntellIJ IDEA documentation was published.
• The less content on a page, the better it’s indexed. Sometimes documentation authors on our team reuse bits and pieces, but the overall section architecture is different. That’s exactly what happened with JetBrains Rider – the information on multiple carets was placed in an isolated help topic, while in IntelliJ IDEA it was a chapter in a larger article, so headings containing the keywords were lower-level.
• SEO specialists also tell us that more traffic and links to a page from other sources also lead to a better ranking, so JetBrains Rider documentation likely contained more references to this section in other articles.

💡 How to avoid

SEO specialists tell us you can avoid traffic cannibalization only if your content is unique. Now that we’ve learned about this phenomenon, should we stop reusing content altogether? Obviously not. The gains of single-sourcing content are still significant.

So my first piece of advice is to BE AWARE of the problem. Forewarned is forearmed. Just remember that your job is not done after you’ve published your content on the web. Well-written documentation has huge marketing potential, so you always need to do everything within your power to ensure that it works, it’s discoverable and accessible, and take action if needed.

When it comes to action, you can do the following:

• If you are reusing content snippets and not entire articles, you can embed metadata into your sources containing more keywords to help search engines distinguish between different target outputs. 
• Schedule updates to make sure different documentation instances containing new content that’s reused are not published with an interval of multiple weeks between them.
• Agree on an optimal article length so that the same content doesn’t appear on different nesting levels in different documentation deliverables.
• Consider using other means to distinguish between different types of content. For example, use tabs.
  Let me show you an example:
  

Here, you could create three separate articles telling users how to install IntelliJ IDEA on different operating systems, and each of them would contain some references to reused content. However, this would literally be pulling the audience in different directions with almost identical content, and search engines would likely rank the most visited page higher, depending on which operating system is more popular among IntelliJ IDEA users.

Instead, you could break these types of content into tabs to make sure readers land on the same page and will be able to quickly navigate to the instructions they need.

Takeaways

Let’s summarize the conclusions we’ve made at JetBrains after about ten years of falling into all the traps of reusing content.

• Whenever you make a decision about reusing some content, always weigh the benefits against the drawbacks. Make sure you are making your life (or your colleagues’ lives) easier and that it’s worth the trouble. 
• Be careful about creating dependencies between reusable chunks of content that imply complex logic. Aim to create stand-alone reusable chunks whose logic won’t be broken by a slight change to a parent snippet or a modification to a pile of filters overriding each other. Strike a balance between reusing content and keeping sources readable and maintainable. 
• Remember that just because you can doesn’t mean you should. Don’t misinterpret the “DRY” principle. Sometimes it’s advisable to sacrifice perfect reuse for a simpler solution. 
• Ask yourself which problem you are trying to solve with content reuse. Maybe you’ll find out there are other, simpler solutions to your problem. Think of our examples, where we suggested automating routine work by creating templates, configuring completion patterns, or splitting similar content across tabs within the same article.
• Remember that your job isn’t done when content is published to the web. Always check whether it’s discoverable after you make any major changes or publish anything new. At the end of the day, it doesn’t matter whether your content is useful if it doesn’t reach your readers.

We hope these tips help you reuse content responsibly! 

How IntelliJ IDEA spellchecks code

IntelliJ IDEA understands that code constructs like classes and methods should not be spellchecked like regular words.

At the same time, it can split complex CamelCase names and check the spelling of each segment. If you misspell a specific word within a class name, IntelliJ IDEA will underline it.

That’s what you get with the built-in spell checker.

Advanced spelling, grammar, and style assistance

Install the Grazie Professional plugin for more advanced checks and suggestions. For example, redundant plurals in code, like entitiesIds instead of entityIds, and much more.

A writing style guide is a set of rules and agreements for everyone involved in writing or editing documentation in a company. Usually, a style guide prescribes using certain words, expressions, terms, and punctuation. It can sometimes go even beyond that and cover content architecture or UI texts.

What are the main benefits of following a style guide? 

• It will be a single point of truth to keep the documentation consistent even when it’s written by a team of writers, each with their own personal writing style.
• It alleviates the editors’ workload coming from external contributors.
• A style guide brings an anonymous authority into the writing process and prevents conflicts.

Do you need to create your own style guide?

Most writing teams rely on several recognized style guides: The Chicago Manual of Style, Microsoft Style Guide, or Google developer documentation style guide. Sometimes companies need to cover cases specific to their industry or business. But even in this case, you can save time and effort basing it on an established style guide.

Let’s look at ten great style guide examples.

The UK Government

The UK Government Digital Service style guide covers grammar and spelling conventions for all content under gov.uk and is a fine example of the signature British writing style. It also has a special COVID-19 section that describes how to communicate on this sensitive topic. 

Mailchimp

The Mailchimp Content Style Guide contains guidelines for all who write content, including documentation, emails, and even legal agreements. It includes tone of voice, grammar, style, and accessibility recommendations. 

RedHat

The RedHat style guide contains not only grammar and style guidelines, but recommendations for the correct markup elements usage. It also describes the appropriate language to use, for example, to avoid slang, neologisms, ambiguity, and anthropomorphism. 

Atlassian 

The Atlassian Design guide contains a content section as well. It covers best practices and patterns for both documentation and conversational writing and provides a lot of detail on inclusive writing. 

Apple

A classic example of a software documentation style guide. It covers a wide range of the writing rules, like how to use terms, units of measurement, numbers, and so on. 

A nice practice to swipe from Apple’s style guide is to have a history of changes so that users can check when the specific rule was introduced. 

Adobe

Adobe, in general leans, on the Associated Press writing standards and their guide is a set of exceptions from it. They also have separate sections dedicated to writing about errors and new user onboarding. 

18F

There is a government related style guide from 18F, which is the US General Services Administration (GSA) internal team who provide digital services for the US government. Their guide is user-centric since the government often addresses a broader audience. The style guide helps users understand what they are saying and keeps them from being wrongly interpreted. A separate section is dedicated to inclusive language. 

GitLab

The GitLab style guide is not only about grammar and style, but about the principles and content architecture they follow. This style guide is used by both the GitLab writers and external contributors. 

It contains guidelines about the topic types they use, documentation-first methodology, markup elements usage, document’s structure, proper directory organization, and much more. It references other recognized technical style guides, like Google and Microsoft, as a primary source of truth. 

SUSE

The SUSE style guide focuses on the document’s purpose and proper structure, but also covers language guidelines, terms and definitions usage, and markup reference. It’s most interesting feature is that it starts with a separate section about how to define your target audience. 

AListApart 

Last but not least, is the A List Apart style guide, which is an example of the reader-first approach. It not only describes how to write and style texts in a clear and concise manner, but also how to treat visual assets. An interesting feature is it describes how and when it is appropriate to use metaphors. 

What will you choose?

Mind, there is no one-size-fits-all when it comes to language and style. So there are two options here:

1. Check which rules and recommendations in other style guides you studied do not suit your case and create exceptions. 
2. Check what rules are missing and create ones from scratch.

Are there other options? Share!

UPD: Use style guides right inside your IDE

Want to check your writing against some recognized industry style guides? Try Grazie Professional.

Grazie Professional is a plugin that works in any IntelliJ-based IDE. Install it on top of the Grazie plugin which is bundled with most IntelliJ-based IDEs. If it’s not, you need to add Grazie first. 

Out of the box, Grazie Professional offers three popular style guides:

• Microsoft Writing Style Guide 
• Google Developer Documentation Style Guide 
• alex linter rules for inconsiderate writing

Open Settings | Editor | Natural Languages | Grammar and Style | Rules and select the rules you want to apply. Switch rules on and off, mix and match them as you need. Just make sure you haven’t checked the same or conflicting rules in different style guides, as they can clash. 

You can also define your project-specific style guide with custom rules and replacements. All to help you maintain a consistent and professional voice across the docs.

Hey, doc! Why so outdated?

Documentation is not source code. For code, you can write tests and check whether it works before the release, but for content-related things, such checks are harder to implement. So the question is this: how can we make sure documentation is up to date and working properly? But before we answer that, let’s take a step back and try to understand why it becomes outdated in the first place. Usually you can blame at least one of these two factors:

1. The docs are too detailed. There is no need to document each line of code if doing so doesn’t solve the readers’ problems. At the same time, it is not easy to find a balance between too little documentation and too much. So the trickiest part of the process is to choose the appropriate level of detail and stick to it throughout the document.
   
   Avoid going too deep into the details, since keeping your docs up to date will become a ball and chain as they grow in size. Get rid of the details that do not add any value. For example, stay on the level of modules or classes rather than functions and variables. Unfortunately, there is no silver bullet here – you just need to make a decision and stick to it. 
   
   
2. Documentation describes an interface instead of user scenarios and the logic behind a solution. This is also called descriptive writing. When this approach is taken, the author describes each window, button, and switcher, even the obvious ones. As a result, documentation gets overloaded with details and becomes outdated quickly as the UI changes. Another approach is action-based writing, where you focus on user scenarios and help solve problems. In this case, you explain the overall logic of the solution and guide the user through some tasks, so a minor change like a new icon won’t be a blocker.

Seeking the golden mean

The methodical effort needed to keep docs up to date does not match the “move fast and break things” approach that is common among software companies. This is why “fast-and-furious” companies often take a reactive, post-processing approach to their docs.

However documentation and code serve different business goals. Code provides customers with the solution they need, but without documentation, code is not a full-fledged product. 

Documentation is a powerful tool that

• Builds trust in your product,
• Boosts customer satisfaction,
• Gives business a competitive advantage.

For example, according to this recent Octoverse report by GitHub, developers see a productivity boost of about 50% with easy-to-source documentation.

When JetBrains recently unveiled the preview for a new IDE, the HackerNews community identified documentation as a competitive advantage:

“In my experience, VSCode is not competitive with JetBrains products. Their products come with support and good documentation”.

The question is not whether to document software, but how to incorporate documentation into a company’s processes without making it an obstacle or an obligation, since this is what best ensures that it stays up to date.

How do we do it at JetBrains? Here are a few tricks.

Work closely with the product and development teams

At JetBrains, we have a working culture of “not me is not an option”, meaning that everyone involved in a process is responsible for its end result. Yes, a technical writer may receive tasks from the product team or the development team. At the same time, writers actively follow product plans and updates and set tasks for themselves because they see a need they can fulfill.

As a writer, you must become a real, proactive member of the development team, not just a silent observer. There are many channels where you can learn about updates. You can, of course, ask developers to notify you every time they need a doc update, but nothing beats direct communication with the engineering team. If you participate in demos, daily meetings, planning sessions, and group chats, you will know what’s going on with the product. 

This approach has one more benefit – technical writers become more integrated into the development process. The developers know that you exist and will ask for your advice and help earlier in the process. It’s a true win-win when this happens.

Store docs closer to the code

Keep documentation in the code repository so developers know where it is. They even can help with updates, at least with a draft version. This also means you’ll have the docs under version control with a record of who changed what.

When we write code and docs in different tools and keep them in different version control systems, we implicitly keep them separated. Keeping the documentation and code together allows us to control changes more easily. There is room for discussion, though. Is it better to place doc files near related source code files or in a separate /docs directory? We use both approaches, depending on the project. 

One last benefit: You can automatically check whether you need to update the docs. For example, you can add a stage to your CI/CD pipeline that raises a warning if the code was updated but the documentation was not.

Get notified about changes

You can automate notifications with a task tracker, setting up a workflow that creates tickets in your task tracker automatically along with the development tickets – for example, when a ticket’s status changes or when it gets a specific tag.

In our team, we set up notifications for UI string changes. All UI strings are kept in property bundles. When a commit affects a resource file, Space automatically creates a review, assigns it to the responsible writers, and notifies them via email. A technical writer reviews changes and accepts them or offers suggestions to the developer about what to adjust. Once the review is finished, Space pushes all changes to Crowdin for translation. Thus we kill three birds with one stone:

• Review UI texts in the product.
• Receive notifications about changes.
• Deliver only grammatically correct and verified strings for localization.

The other side of the coin is that sometimes the implementation or even the development direction of products change, which can result in duplicate work or long-running tickets. Bear this in mind as a possible tradeoff.

Another option is to set up notifications about code changes in Slack (or another corporate messenger). In JetBrains Space you can set up integration with Slack using webhooks to send such notifications. The same is true for GitHub, GitLab and Bitbucket.

The main point is to choose what triggers notifications. Some options to consider are:

• Any changes in the code
• Only major changes (new classes, models, or views, for example)
• New pull requests
• Data structure changes

Based on our business needs, we decided to go with notifications for UI string changes and significant code updates. Choose what’s best for you.

Schedule updates

You can store the timestamp for each document and create a schedule for regular maintenance. For example, employees at gov.uk set a “review by” date for each page and set up a bot that sends an automatic reminder to perform reviews.

They called it Daniel the Manual Spaniel and even made it open-source so you can adapt it to your workflow.

Of course this approach is time consuming if you have a lot of documentation and barely enough time to prepare it, let alone enough time for regular reviews. Nevertheless, you can give it a try, at least for popular or critical pages of your documentation. See which pages get the most views according to an analytic tool or most responses via a feedback widget. 

You can also experiment with using different review periods for different articles depending on your workload.

We’ve decided to make Monday a dedicated day for updates and content rework and set the reminder for ourselves. We will let you know how it worked for us in later posts.

Automate wisely

Docs usually consist of free-form prose that explains concepts and approaches, in addition to non-free-form material that can be automated. 

Use automation where appropriate: 

• Do not hardcode shortcuts — we reference them from the special artifact that in turn extracts them from the product source code. 
• Extract icons and UI strings from source as well — we reference them using an ID or a property key.
• Auto-generate the reference sections, like we do for the list of inspections – colleagues from Kotlin auto-generate all of their code documentation with a tool called Dokka.
• Reference code stored in a repository as code samples – we indicate a range or lines or an entire file. This prevents samples from becoming outdated. 

You can do more than just reference code samples from the repository. In fact, you can even make unit tests for each one. If the test fails, it means that something has changed in the behavior, and you need to update not only a code sample but the doc itself.

Screenshot updates are another automation feature that would make any technical writer jump with joy. 

Our team has been experimenting with a tool that generates multiple variants of each screenshot depending on the user’s environment, language, and theme. The idea is still kind of up in the air, but the trick is not to overcomplicate the documentation process. Can we come up with a tool that solves this problem? Stay tuned.

The major downside of automation is obvious: You don’t have control over changes, and if something breaks, you might not even know that you have a bug in your docs. So always bear in mind that there are both benefits and risks. We’ve only had to deal with a couple of curveballs of this sort, which isn’t so bad overall.

Will new tooling help?

The idea of documentation coupled with code lays the foundation for new tools and startups. Take Swimm, Nots.io or HastyDocs, for instance. All of these tools link code with documentation through the use of certain tags or comments. Then the tool incorporated into your delivery pipeline follows changes in code and flags docs as outdated.

Keeping docs up to date is a meta-task that requires soft skills as much as automation and tooling. Combine active team communication with code/docs transparency, set up change notifications, use automation wherever possible in the code samples, and maybe (just maybe!) you won’t miss that update again. 

This post cannot describe a complete solution to the problem of keeping documentation up to date. We’ll be happy to learn from you and your experience. What works for you and what doesn’t? What new tooling are we missing out on?

Share in the comments, let’s talk.