Home »

Write the Docs Newsletter – March 2024¶

Ahoy, documentarians! The sun is shining more and more each day where I am, which brings with it a sense of growing optimism and energy. I hope you can find such positive signs in your own lives, whatever they may be.

In community news, the Portland 2024 conference has announced its schedule. So check out all the talks and start planning your experience.

This month’s articles cover iterating your writing with a chatbot, what good design is for documentation, and how to overcome frustration at bureaucracy. Hope you enjoy and see you again next month!

Iterative Writing with a Chatbot¶

Artificial intelligence (AI) continues to be a popular subject in WTD Slack, and #ai is a busy channel. Recently, one documentarian shared an AI success story: a chatbot integrated into Slack that uses content from their docs to respond to questions. Employees testing this particular chatbot have been impressed with the answer quality. It seems to be driving increased docs usage (it helped overcome barriers to docs adoption such as being forced to log in).

Getting the chatbot working optimally with the docs was a process. To test responses, the documentarian asked variations of common questions, often actual customer questions. Then, they examined the chatbot’s responses for any unclear or incorrect information and adjusted the docs as needed. After giving the large language model (LLM) time to retrain on the updated documentation, the documentarian repeated the questions to confirm that the response was as clear and accurate as possible.

The discussion of this process led to a few takeaways:

Writing for AI can make content more accessible and easier to understand for most docs users, not just those who use the chatbot. For example, asking an AI system to summarize a page of content highlighted unclear areas. This resulted in improvements throughout the documentation.
Making documentation more structured and explicit seems to help LLMs train more effectively.
AI systems that pull from docs content may still give confusing or incorrect answers, even if the docs themselves include a clear explanation. In this case, the chatbot still confuses different types of tokens even though the docs include explicit sections for each type of token.
The manual nature of the testing illustrates that AI tools definitely require human control and optimization.

Design of Technical Communication¶

What skills do technical writers need to present content? Some people think that a “skilled” technical writer is one that writes well and can use (or adjust) design resources to produce effective documentation. So being competent in document design (or visual design) may be as important as information architecture (IA) and clarity in writing. What you’re documenting (the complexity of the product) and the audience can affect design decisions.

What design skills and concepts should an average tech writer know and have? Design decisions can include visual consistency (such as formatting and layout), color and contrast, table design, mobile-responsiveness (for online content), and more. Your tool set may constrain some design decisions. With small companies, a documentarian may need to create and implement the documentation design. Larger companies may have a graphics design team or marketing department that provide a color scheme and branding guidelines or even be responsible for the overall design.

As a documentarian, your skill set and experience may determine whether you implement provided guidelines or develop (or contribute to) guidelines and standards. The status of the existing documentation may determine whether to continue using a design or take part in a re-design effort. Switching tool sets may require significant design changes. Priorities and time constraints may downgrade design considerations.

Recommendations for document design books include: Don’t Make Me Think, The Design of Everyday Things, Document Design: A Guide for Technical Communicators, and How To Make Sense of Any Mess.

For visual communication books, see: Stuck? Diagrams Help, The Visual Display of Quantitative Information, The Wall Street Journal Guide to Information Graphics: The Dos and Don’ts of Presenting Data, Facts, and Figures, and a comprehensive list of visual design books. The Portland 2023 conference had a relevant talk: The visuals your users never saw…wait that’s most of them. The upcoming 2024 conference offers Graphic Relief: Beyond Flowcharts and Screenshots.

Dealing with Feeling Blocked by Bureaucracy¶

As revealed in a recent discussion, stagnation amid bureaucratic challenges can be a common struggle. Documentarians expressed a sense of frustration and stagnation despite accumulating valuable skills. The recurring theme was proposing solutions only to encounter bureaucratic obstacles, leading to a cycle of unfulfilled potential.

The discussion highlighted the dichotomy between environments conducive to “rest and vest” (encouraging stagnation) versus those providing continual challenges. Mid-career professionals emphasized the need for engagement through challenges. The conversation also highlighted the impact on specific roles, such as documentation, where blame was unfairly assigned amid broader organizational challenges.

If you are dealing with feeling stagnant, here are some helpful action items:

Seek New Challenges: Recognize the importance of continual challenges to professional growth. If your current environment leans towards a “rest and vest” mentality, consider exploring opportunities in startups or smaller companies that provide a more dynamic and engaging work environment.
Build Alliances and Influence: Identify key stakeholders and influencers within and outside your team and develop relationships and alliances with them. Building a network of allies across different teams can be instrumental in overcoming bureaucratic resistance.
Strategic Communication: When faced with blockers, employ strategic communication. Utilize allies in other teams to convey messages to influential figures who can support your ideas.
Develop a Long-Term Plan: Take your time developing a long-term plan. Understand the organizational dynamics, identify blockers, and work on gradually building support. Patiently wait for opportune moments to present and implement your ideas.
Stay Adaptable: Recognize the need for adaptability in the face of bureaucratic challenges. Understand that change may take time and maintaining resilience is crucial. Stay open to revising strategies based on evolving circumstances.
Explore New Avenues: Consider alternative career paths within your field. One contributor shared that transitioning to a DevOps role provided new challenges and leadership opportunities. Exploring adjacent roles can lead to fresh perspectives and career growth.