To the untrained eye, software development can be a big, scary place. The industry hosts a complex, elaborate landscape full of particular terms and expressions.
For example, how often have you heard medical staff say: ‘oh, we’re Agile’? Have you ever met a salesman who has a ‘debugging process’? Probably never.
All these new words can be intimidating when compiling software documentation, especially if you’re just starting as a technical writer.
That’s why we’ve put together this glossary of software development terms: so you always have a guide to refer to when writing software documentation.
Documentation Guide
A documentation guide is an extensive project document without which you couldn’t even begin the documentation process.
This guide will specify must-know information such as content, format, terminology, chapter outline, and similar.
In other words, it serves as a reference point while you write your documents.
Here’s an example of a documentation guide:
As you can see, this documentation guide has instructions on almost all aspects of technical writing, making it an invaluable resource.
We suggest you start writing only after you have familiarized yourself with an approved documentation guide, as it will significantly facilitate the process.
Manual
A manual is a set of instructions for various circumstances that users keep ‘on hand.’ Product installation, configuration, and system administration manuals are the most common variants.
If you hear the term ‘guide,’ this can also be used interchangeably with ‘manual’; the meaning is the same.
Manuals can more or less be divided into the following three categories:
This organization is divided by intended audience groups.
In other words, manuals will differ in style and content based on who you’re writing for, whether end-users, vendors and contractors, or developers.
SME
SME stands for ‘subject matter expert.’ They are knowledgeable individuals specialized in their chosen fields and are invaluable resources when writing technical documents.
It’s a good idea to interview SMEs before writing, as they can often provide valuable data and feedback.
As a technical writer, your job is to translate their knowledge into a language that the general public can easily understand.
Here are some SME examples:
As you can see, SMEs are experienced professionals with unique expertise.
Their input is a considerable resource while writing; they might even review your document afterward for any errors.
Functional Writing
Functional writing is a subset of technical writing that deals purely with operational elements; it describes the what, not the how.
This writing will explain in detail what each component or part does.
Imagine your standard Word ribbon. You’ll find options like ‘File,’ ‘Edit,’ ‘View,’ and similar.
Functional writing will detail the function of every such button and describe all the options in the drop-down menu that appears after clicking on them.
For example, look at this image:
In functional writing, every element on this page - even those not highlighted - would be extensively explained and documented.
Procedural Writing
Procedural writing can be considered the direct opposite of functional writing. Instead of listing functions, procedural writing describes how the users would utilize the product.
It places the product in the context of use cases.
To accomplish procedural writing, you should have a very good understanding of performance goals—the main objective when using a product.
Here’s a sample performance goal from Stripe:
This goal is clear: build a customized payment page for desktop and mobile devices.
In procedural writing, always keep this goal in mind, and try to compose a document that will help the user achieve this objective.
Documentation Review
Before a text can be approved and published, it’s a good idea to have someone look over the document and double-check that everything is in order.
This is precisely what documentation review entails—feedback on the text and an opportunity to suggest improvements.
A crucial part of the documentation process, this is what an ideal review procedure looks like:
However, keep in mind that this process is often a long one.
Reviewers tend to be SMEs and have numerous other duties in a corporate setting, so the review period can easily be extended due to their limited availability.
Document Management
Document management, also called content management, is concerned with developing a documentation structure.
The aim is to organize documents in a logical and accessible manner, so employees can quickly locate the information they need.
One of the easiest methods for this is a documentation platform. That way, you’ll host all your documents in one location, making them extremely easy to find.
Furthermore, some documentation platforms offer a search function and a table of contents. Take a look at these functions in Archbee:
With a documentation platform, all your documents will be in one location, significantly streamlining team collaboration.
Lifecycle
A lifecycle refers to the continuous work done on products or applications, from the day development starts until they are no longer used.
This process usually begins with planning, encompasses development, and ends with maintenance or retirement.
For your better understanding, here’s an example of the typical document development life cycle:
As you can see, the extensive process covers every aspect of a product’s lifetime.
While working on projects, technical writers are usually included from the beginning to the end, as they’ll need to document all stages of the product’s development for better future reference.
Stakeholders
Stakeholders refer to every individual involved in the product development process; everyone with an investment or an interest.
They can be either external or internal, depending on their relation to the company.
The visual below shows the most common stakeholders:
Depending on the stakeholders you’re writing for, the tone and content of your documentation will change.
For example, you’ll write user guides and manuals for customers, compose records and summaries for shareholders, and develop various types of internal documentation for employees.
In a software development context, these internal documents can be software testing documentation, API documentation, and more.
Information Architecture
Information architecture focuses on structuring, presenting, and labeling content effectively and continuously.
In other words, it deals with how information inside a document is given; in which order, and in what format.
The screenshot below is an excellent example of quality information architecture:
The information in this screenshot is clearly displayed and easily navigable.
Similar content is consolidated in one group (e.g., ACME versions into ACME Series), and each group has an overarching theme.
Furthermore, these content groups are color-coded, providing additional visual aid to differentiate the two types of information.
Software Build
Software development is a continuous process in which developers constantly edit, remove, input, and refactor their code.
Depending on the company and its internal processes, the software can be compiled daily, twice a week, weekly, or bi-weekly; the business decides whatever timeline suits them best.
Each of these new versions of the source code is called a build. Builds are a standard part of the CI/CD pipeline, as displayed in the visual below:
As you can see, developing a build is the last step before beginning testing and eventually deploying the software.
Release
A release is a process of providing users with the latest software version (or build).
Usually, this new version significantly differs from the previous version in several ways and is a significant milestone in the product’s lifecycle.
The image below shows three distinct software releases and the new features of each release.
Each release comes with multiple new aspects that will enrich the customer experience.
Given the broad scope of changes, a release only happens once or twice a year. In fact, it’s not unusual for companies to issue a release only once every few years.
Software Release Notes
Software release notes are a document that outlines the changes that have been made in the latest software release.
It’s essential to explain what has changed, how the new edit functions, and why this release will improve the user experience.
Release notes should typically contain the following information:
If your release notes contain the above components, you’ll be much more likely to have a quality document on your hands.
When writing the release notes, use plain language, and keep the content short and sweet.
Your aim is for the document to be easily digestible and understandable without too much technical jargon.
Bug
A bug is a term used to describe errors in software that are caused by mistakes in the codebase. They result in a program not acting as intended or even crashing completely.
Clearing bugs from the codebase is called ‘debugging’ and will result in more efficient and functional software.
There are several types of bug tracking software that can help stay on top of these errors and facilitate debugging. Here’s an example:
As a technical writer, one of your tasks could be to write bug reports. If so, investing in one such bug tracking tool might be wise.
Version Control
Version control is the process of tracking edits in a file.
This practice is an essential and necessary component in all software documentation, as it makes it possible to identify different file versions.
Furthermore, it provides a clear overview of changes made to a product or feature, which can be helpful when making business decisions.
Here’s what version control looks like with Archbee:
Archbee’s version control provides a document’s history for up to 12 months, allowing you to really drill down into the changes made.
If required, you can also effortlessly revert to the old versions.
Configuration
Software configuration is a procedure in which the software that makes up an app is defined and managed.
This is an extensive process, and larger companies might have a team whose sole task is configuring software.
Configuration includes selecting applications for a project, deciding how they should be configured, what their dependencies are, and more.
Given the considerable scope, companies often uphold a configuration management plan, typically composed by a technical writer.
Here’s a standard table of contents in an example configuration plan:
With this document, you’ll create a framework to keep track of all changes in your software’s configuration.
Agile
Agile is a software development methodology that values quality over quantity.
This framework takes an iterative approach, advocating that developers work in short cycles of time (typically one to four weeks) called sprints.
During these sprints, quality is preferred over quantity, as developers do their best to plan out and complete a set of tasks.
Agile supports flexibility and a team-oriented approach to solving problems, which encourages collaboration among developers. Its core values are summarized in the following four principles:
These four sentences succinctly encompass Agile’s central philosophy, as the methodology significantly emphasizes cooperation and adaptability.
Gamification
Gamification is the inclusion of design game elements in non-game environments. In software development, gamification can motivate developers to adopt certain programming practices.
For example, gamification has been used to incite the Agile methodology. Since this is a new model compared to Waterfall, acquisition can be slow.
However, engagement with Agile can increase by implementing game-like elements and rewards.
Gamification is also present in online programming learning portals. Codecademy, for example, has devised a badge system for users’ achievements.
Here are the available badges:
These badges result from gamification; users are rewarded with items for their efforts.
Specs
Specs, or specifications, is a document that provides a detailed description of system requirements.
This text makes it easier for developers to understand the needs of the system, which then aids their planning.
Specs typically describe why the system is being developed, its functions, limitations, and similar.
All this information should be highly detailed so as to be as helpful as possible to the developers.
Here’s an example specifications document:
As you can see, the document encompasses external interface requirements, deals with user environments, and details the system’s features.
Quality Assurance
Quality Assurance is an extensive testing process where testers evaluate to which degree a product delivers what it is supposed to.
Before a product is released, QA testing must give the product the ‘green light’ for market suitability.
Several types of documentation are involved with Quality Assurance, including a test strategy, a test plan, a testing checklist, etc. As a technical writer, you’ll likely compose these texts.
Here’s a testing checklist example:
With this document, you can ensure that QA testers will do their job thoroughly, as they’ll have a written record of necessary test requirements.
Use Cases
Use cases document interactions between the user and the system. This is done to determine the correctness and completeness of system requirements.
Because of their insight into software requirements, these texts are a great asset for developers during the planning process.
In other words, they help developers see what users will want from the product.
There are two types of use cases:
Functional use cases are focused exclusively on the system’s behavior, taking stock of how it performs and why.
Non-functional use cases detail the system’s attributes, dealing with technical elements such as reliability and maintainability.
Conclusion
Software development is a multi-layered, intricate industry with more or less its own language.
A technical writer from a medical or machine field, for example, won’t have an easy time in software development.
However, with this comprehensive guide, you’ll never wonder about software development terms again.
From business phrases such as ‘stakeholders’ to software expressions such as ‘version control,’ ‘configuration,’ and ‘build,’ this glossary lists everything you’ll need to know when writing software documentation.
When in doubt, check back here—you’ll find the answer.
