While the principles of the Plain Language standard (ISO 24495-1) apply broadly, they are especially valuable in software projects, where documentation must guide diverse audiences—from developers to end-users. Whether drafting requirements, design specs, or user guides, applying plain language throughout the development cycle, project managers and DevOps teams can enhance clarity, reduce friction, and build credibility with stakeholders and users alike.
History and Purpose of the Plain Language Standard
Published in 2023, it is the first international standard dedicated to plain language. It is a globally recognized framework that ensures quality of digital and written text documents, a solution to documents that are often too complex, legalistic, or jargon-heavy, leading to misunderstandings, inefficiencies, and reduced trust. While it doesn’t cover all media types, its recommendations are useful also for other media formats like podcasts and videos.
Before the publication of the standard, notable developments occurred across different parts of the world mainly with the objective of promoting clarity and accessibility in communication. These include, for example, the European Commission’s guide How to write clearly, the US Plain Writing Act of 2010, or the non-profit Plain Language Association International (PLAIN) from Canada.
In the IT sector, controlled languages such as Simplified Technical English, the Microsoft Writing Style Guide, IBM Style Guide, and style guides from companies like Google and Adobe have helped standardize terminology and improve readability. To support organizations in adopting plain language practices, qualified trainers and consultants are available to guide implementation, ensuring that communication is both effective and inclusive.
What the ISO Contains
It outlines four governing principles for plain language communication:
- Relevance – This principle emphasizes the importance of preparation before drafting begins. As an author you must first understand the characteristics of the readers and what they need. In doing so you must choose the appropriate document type and tailor its content to suit the readers’ purpose and context.
- Findability – Information is easy to locate through structural elements, various information techniques that increase the speed of reading, and keeping additional information separate like appendices or bibliographies.
- Understandability – The aim is to create a cohesive document by using familiar words, clear and concise sentences and paragraphs, being consistent, making the information easier to process by using images and multimedia, and using a respectful tone
- Usability – You need to evaluate a document throughout its life cycle so it is up to date
The Role of Technical Writing in Software Projects: A Conceptual Overview
Technical writing is an important aspect throughout the lifecycle of a software project. It ensures that information is clearly communicated among stakeholders, developers, testers, and end-users. This article outlines the key stages of the writing process and the various types of documentation required at each phase of a software project.
Planning phase: purpose, audience, and delivery
Planning is the cornerstone of successful software documentation. A well-structured planning phase not only guides the creation of documentation throughout the software development cycle but also serves as a reference point for future team members. When new members join the product team, having a documented foundation allows them to quickly understand the system’s layout, business logic, technology and expectations—reducing onboarding time and driving continuity.
Purpose
Each document type has a distinct purpose aligned with its audience and phase in the project, such as:
- Persuade stakeholders to fund your project;
- Choose whether to act or not;
- Try to make sense of a subject;
- Discover more about a topic they care about, for example a conceptual user guide article.
- Learn what’s needed to reach a goal, like prerequisites to use a product or dependencies.
- Attracting people to use your product, a new release note with critical bug fixes or user requested features.
Audience
Documentation may target multiple audiences (e.g., developers, testers, end-users), requiring tailored formats or separate documents for clarity. When thinking about the audience, the authors should consider:
- Technical proficiency
- Prior knowledge
- Context and environment
- Emotional state and urgency
- Cultural tone and expectations
Delivery
The format and medium of the text must suit the audience’s context. For example, a troubleshooting guide for system outages should be delivered as a printed quick-reference sheet in the server room, rather than as an online document, since DevOps engineers may not have internet access during critical downtime.
Research phase: extracting knowledge
There are various methods in which you can gather information:
SME Interviews: you should prepare targeted questions and put yourself in the shoes of the reader when conducting them. This is a good way to find out about the real-world usage of your product and get accurate technical information.
Existing Documentation: if you are onboarding a mature product, you can always review prior materials for continuity and completeness.
Use of the software: Use the product to understand how it works and feels, identify areas of it that might need more detailed documentation.
Writing phase: drafting and structuring
When writing your first draft, you should focus on the content rather than spending time on layout or visuals. It will go through multiple refinements before it is delivered.
When you’re drafting documentation, keep the four plain language principles from the ISO in mind—make sure your content is relevant, easy to find, simple to understand, and useful to the reader. It’s the kind of clarity that makes your docs work for real people, not just tick a box.
Reviewing and editing phase: refinement and usability testing
I believe that usability testing is the most useful method to check if the notes you take during SME interviews and your first draft are both correct and relevant.
To make sure that your readers can complete the instructions you wrote or use whatever information you prepared for them without confusion you can turn to peer review done by your colleagues or tools like Grammarly or conversational/generative AI to perform style and grammar checks.
Launch phase: release and maintenance
Documentation is typically released alongside the software and should be treated as a living asset, requiring regular updates to remain relevant. The key point to take into consideration during this phase are:
- Translation for global audiences
- Coordination with development, release and marketing teams
- Planning for ongoing updates as the software evolves
Types of documentation across the software lifecycle
Requirements documentation
Defines what the software must do. It must be clear, traceable, and verifiable because it will further support the design and testing. This type usually includes the following:
- User Stories: Simple, goal-oriented statements from the user’s perspective.
- Text-Based Requirements: Formal statements specifying functionality.
- Use Cases: Detailed narratives describing interactions between users and systems.
Design/architecture documentation
Outlines how the system will be built. It supports alignment across development teams and serves as a reference for future maintenance. This type usually includes the following:
- System architecture diagrams
- Detailed component descriptions
- Data design (schemas, ERDs)
- User interface mockups
Code documentation
Supports developers in understanding and maintaining code and makes the onboarding of new developers much smoother. This type usually includes the following:
- Code Comments: Should be high-level and meaningful, avoiding redundancy.
- API Documentation: Describes how to use software interfaces, including method signatures, parameters, and examples.
- README Files: Provide installation instructions, versioning, and usage notes.
Test plans and test cases
Ensure the software meets requirements and functions correctly. This type usually includes the following:
- Test Plans: Outline strategy, scope, environment, and defect management.
- Test Cases: Step-by-step instructions for validating specific functionality.
- Test Scenarios: Group related test cases for easier management.
End-user documentation
End-user documentation must be accessible, clear, and tailored to diverse audiences like testers, trainers, system administrators, or the general public. This type usually includes the following:
- User Guides: Comprehensive manuals covering installation and usage.
- Quick Reference Guides: One-page summaries or job aids for common tasks.
- Release Notes: Summarize changes between software versions, including bug fixes and new features.
