Similarities Between Technical Doc Writers and Software Engineers
I'm a software engineer, working for Oxygen XML Editor along side my colleagues in developing tools used by technical documentation writers. I also do lots of technical support and sometimes I write small blog posts like this one or update our technical documentation.
Over time, I've come to view the aspects of a technical writer's job (especially a tech writer who is using standards that have lots of potential for reuse, like DITA XML) quite similar to many of the aspects of a software developer's job. So I started putting together a list of concepts and the way in which both of these jobs (which may seem incompatible with each other at first) would utilize such concepts.
| Concept | Software Engineers | Tech Docs Writer |
|---|---|---|
| Accessibility | We build our software products by following accessibility best practices, we test our products using screen readers and collaborate with our vision-impaired users to fix accessibility problems. We also try to make sure there is enough color contrast in the application components and icons, that all font sizes are configurable and ship various color themes for the application. | Published technical documentation also needs to be accessible, for example by adding alternate text for images and using relevant text for links. It's also important to make sure the color theme of the published output has enough contrast. WebHelp and PDF outputs obtained using Oxygen from DITA XML content are section 508 compliant. |
| Accurate and Concise Messages | We are required to present accurate and concise error messages, dialogs, and prompts to our end users. Over time, we've learned to pass most of these error messages by our tech docs writers, asking their opinion to help improve them. | The technical documentation must also be accurate and concise. The technical writer's advice can also greatly benefit the software developers when they work in developing the messages in the application. |
| Balance between Time and Impact | Time is a precious commodity, as an engineer I need to make the best of the time I have allocated in order to implement a certain feature or functionality or to refactor content. If time does not allow me to perform a full redesign of a certain functionality I can still gradually improve it. | The tech docs writer may also not have enough time to refactor for example the entire project in a certain way but can gradually work towards a certain direction. |
| Building Complex Systems from Basic Building Blocks | We build small components (classes) and then we use them to build
projects. We then use the many individual projects to build entire
large products. We keep the small components as simple as possible to maximize their reuse potential. With these simple components, we build large complex projects. |
Publications are built by using small topics of information or
small reusable elements like notes or tables. Even larger
publications can be built by combining the DITA maps used to
describe subcomponents of the product. Individual topics/tasks are small, simple, and easy to follow. With these simple topics, you can build large technical documentation projects. |
| Code Review | We have a stage where the code that was written by someone is reviewed by a usually more experienced peer. The code reviewer may propose various changes, either small message changes or changes from the point of view of someone who knows the architecture of the project better. There is also the possibility for a novice to code review, as this exposes them to new techniques and they also can give a fresh perspective on things. | Having experienced technical writers review the work of novice writers is a great way to acclimate the novice writers to a specific way that the content must be written for a certain company. Experienced tech writers can also, for example, better determine if the content should be placed somewhere else in the project or if the current topic should be split into multiple ones as they have a better overall overview of the project. |
| Content Reuse | We reuse entire small projects in multiple products. We reuse libraries, classes, and functions. Content reuse gives us the ability to build products faster and to build different products from the same content. | Similarly, starting from the top down, entire DITA maps can be
joined together to create documentation for larger publications,
topics can be used in multiple places in a DITA map, and elements
like notes, tables, lists can be reused in multiple places. Useful
links: |
| Copy/Paste vs Reuse |
Sometimes I may decide that it's in the best interest of the project I'm working on to copy/paste instead of reusing. I may prefer copy/pasting for example in order not to introduce dependencies between modules or when using incompatible data formats. Or if I plan to alter the content in certain ways. I may create auto tests to notify you when the source of truth has changed. |
It's best to reuse as much as possible but sometimes the writer may decide that copy/pasting and then maybe making small adjustments is a better decision. |
| Custom Validation Rules | We have various automatic tools (like Sonar) that report warnings when certain best practices for writing the code are not followed. This gives us more consistency as we are many devs working on the same code base and the code we produce needs to be easily read, understood, and maintained by others. | Using Schematron Rules, technical writers also can impose custom validation rules, specific for their project. These custom validation rules ensure consistency throughout the tech docs project. |
| Deleting Unused/Deprecated Content | All mature software products contain components that in time may become unmaintained or unused. Over time, such components may become security problems or may just contain inaccurate information. So, software developers also spend time deprecating and then removing these components. | Technical documentation also may contain content that is no longer accurate or topics that refer to features that no longer exist. So, deleting unused content is also a part of a tech writer's job. |
| Document my Code/Documentation | Most programming languages have support to add comments containing documentation about what the code does and why various choices were made. This documentation gives more information that could not be derived just by reading the code. We also have internal wikis with diagrams and descriptions of various architecture choices and steps to set up various projects for people who just started working on them. | It's a best practice to try Implementing your own Style Guide where various best practices and architectural decisions for the documentation project are described. Such a Style Guide makes on-boarding easier and over time, the rules in the style guide may start to be automatically applied using Schematron or a terminology checker. Publishing customizations should also be documented in a style guide and a quick getting started tutorial for people who start working on the specific technical documentation project may also be useful. |
| Enjoy | For the long term, it's good to find particular aspects about your job that you particularly enjoy doing. For example, in my case I've always been interested in investigating why certain bugs occur and following through, spending hours to investigate and solve them. I'm also very eager to delete unused code and functionality. | Whether it's rewriting/correcting problems in existing content, writing new content, adding custom validation rules, helping others, discussing with engineers, or improving the architecture of the existing technical documentation project, technical writers may also have preferred activities. In general, we get to know what each person does best within the team and who to ask for advice in certain cases. |
| Evolve | We need to constantly deepen our understanding of the current techniques we use, learn new techniques, and new frameworks or programming languages. Learning new things also helps us to obtain a different view of the current techniques we are using. | By reading various resources like the DITA Style Guide, the DITA 1.3 standard, or the Oxygen XML Blog, a technical writers
can deepen their understanding of the used standard, what features
it offers, and what best practices to follow. There are lots of useful resources about approaching technical documentation online like: Diátaxis. And various community places where one can ask for help or follow up on conversations. Sometimes, technical writers also become involved in styling the published HTML or PDF outputs, in uploading the deliverables to the proper places on the web site, producing training material, or receiving user feedback and integrating it back in the documentation. So, they move towards scripting and being power-users. |
| Helping Yourself | When I do not know how to do something, I first try to figure things out on my one before asking for help. I use various internal resources (our internal wiki) or external resources like Google, ChatGPT, StackOverflow. I always tend to remember the solution better if I put some effort into finding it myself. | Overcoming obstacles by oneself is possible if the company has internal wikis or internal style guides that the technical writers can use. By helping ourselves, experienced writers develop a certain grit that allows them to overcome daily obstacles. |
| Inversion of Control | Most of the time, we use libraries developed by us or by others to build larger projects. So, our code uses other code. But there are frameworks like Java Spring that have this concept of inversion of control. With this concept, our code does not use libraries, but those libraries in turn orchestrate and use our code. | The DITA XML standard has the concept of key scopes, which
allows key references and content key references in topics to have
different values depending on where the topic is referenced in the
DITA map. So in a way, your topics contain variable place holders
that may expand to different content depending on where they are
used in the DITA Map. The DITA XML standard also has this concept of content reference push. With conref push content can be placed in a topic from the outside. A DITA topic that contains key references is not truly instantiated until it's referenced in a certain place in the DITA map. |
| Issues/Tickets List | We work internally mostly with Atlassian
JIRA to create issues/tickets. We have various workflows for
our issues that allow us to have quality assurance, and
documentation connected to the same issue ID. The issue connects all
the commits and modifications made both in the development phase and
in the documentation phase. So, looking at an issue, I can also see
links to all changes made to fix and document the issue. For some projects, we also work with GitHub issues or GitLab issues/tickets and although more simple, they also provide us with some basic way of keeping track of work progress. |
An issues/tickets list is also very important for tech doc writers to keep track of what needs to be done. |
| Learn by Teaching | Teaching is a great way to learn more about the concepts yourself. You do not need to be highly experienced in a subject matter in order to make small presentations in the team about it. I sometimes make small presentations to start discussions about the subject matter and gather best practices from other team members who now more about the subject matter than I do. | You can read about an aspect of a standard like DITA XML that you are not using in the company (for example, about branch filtering or relationship tables), make a small presentation in the team, and then try to start a discussion about how the feature could be used in the tech docs project and what problems it could solve. |
| Managing Dependencies/Linking between objects | The more dependencies a class, object, or project has, the more difficult is to use it in another context. In our work, we try to uncouple objects, to decrease the dependencies between them to be able to reuse the objects in multiple contexts. | There are various linking strategies, the main idea being to avoid direct references between topics and instead use indirect links and relationship tables. This gives you more flexibility to re-use topics in multiple contexts. |
| Metadata/Extensibility | From the point of view of a Java developer like myself, support for annotations was added to the Java programming language about 20 years ago and it allowed the creation of various important libraries that in a way extend the language to offer all kinds of useful functionality. | The DITA XML standard has various ways that users can enhance the
publishing or add metadata that is useful for specific needs:
This possibility to extend the standard makes it much more valuable and allows targeting specific company needs. |
| No Appreciation for Fluff | The written code should be as compact and easy to read as possible. An application's features should again be intuitive to use with a user's interface that does not present more than you need to accomplish a certain task. | Small topics describing key concepts, small tasks describing how various things can be accomplished. Precise messages, simplified English, no fancy words, no thesaurus. |
| Obtaining multiple products from the same code base | Using configuration files, we can reuse an entire product code base to create multiple products, each with a specific subset of features. | Using profiling/filters or multiple main DITA maps, a DITA XML based project can be used to create user guides for multiple products. |
| One trick pony / Jack of all trades | Even if over time we specialize and become very productive with one set of tools and when working on a certain aspect of the application, having a larger overview and being able to use other tools/languages/frameworks when necessary gives us lots of flexibility to help members of other teams or to make changes to sub-projects that we are not directly involved in. | Being able to write documentation in multiple formats (Markdown, DITA XML, MS Word), being able to use various version control systems like Git or content management systems gives you the ability to apply for and be able to perform any technical documentation job, besides the benefit of using much of the workflows and tools other people in the company might use. |
| Overview of Complex Systems | Either when making a small improvement or implementing a large feature, having an overview of the entire project's architecture helps a lot. | Having an overview of the documentation project helps you know where to make a change, what pleasant or unpleasant side effects it generates and how to possibly re-structure the content to facilitate making that change. Content reuse adds a lot of efficiency to the process of building a user's guide and reusing large chunks of content between user manuals. Content reuse unfortunately also sometimes makes it easier to propagate errors in multiple places. |
| Pair Programming | We have this concept that we apply from time to time in which two people work on the same issue from the same computer. These people can be peers with the same knowledge, in which case one of them thinks about the larger context in which the issue is resolved and asks questions while the other implements it. Or the engineers can be an expert and a novice, in which case the novice directly sees how the expert considers and implements the issue. | I'm not sure if in the domain of tech docs writing people use such pair docs writing but I think it could also benefit a novice to see exactly how people with more experience organize themselves, understand the requirements, and work on issues. |
| Project Structure and Naming Resources | Experienced software developers are interested in properly naming things. We try to give good names to functions, variables, and packages. We try to be consistent when naming things using compound names, either using hyphens or upper-lower-case sequences. | It makes sense for technical documentation writers to also have best practices when it comes to a project's structure, how files should be named, where images should be stored, how key names should be given, and so on. Sample Project. |
| Publishing Orchestration | We have various automated flows that generate nightly build installation kits for our product that can be further tested by the QA team. | Although the published output can be obtained from an Oxygen installation by running a transformation scenario, over time it's a good idea to automate the publishing by using an integration server like Jenkins, for example, to constantly poll the user guide project for modifications and update an internal web site with the latest HTML or PDF outputs to show how the documentation is evolving and give material to engineers who want to review the published content. For the Oxygen XML blog, for example, a Gradle build file is used to automate the publishing. |
| Read the Docs | We learn a lot by doing, or by copy pasting or reusing content from other similar projects that we have. But sometimes taking the time to read the documentation for the frameworks and libraries that we use is really worth it. | By reading the DITA 1.3 standard documentation, for
example, a technical documentation writer might find various
features that can be used in their project. They might also
understand certain limitations in the way things work. There are lots of resources for learning DITA or for learning how to better use Oxygen to edit DITA XML content. So, it is sometimes worth taking the time to explore the tools you are using and the capabilities of the standard. |
| Requesting Help from Peers | Besides an internal wiki of content and procedures, we rely on a network of colleagues, some from our teams, some from others or from the system admins team. Over time, we come to know each other's strengths and know who to call when we need advice. Helping someone else usually takes priority over the current task. | Besides asking their peers for help, technical documentation writers also have various engineers and subject matter experts who could help when writing content either by giving feedback or by providing some initial content (some notes for example) to be used for the official documentation. |
| Security | We do our best to protect our applications from security vulnerabilities by updating old libraries and by considering various scenarios in which attackers would attempt to gain control over an application. | Besides keeping the user guide contents in a secure location to
avoid exposing information to the competition or features that have
not yet been released, the HTML output obtained from the user guide
contents also needs to be updated to contain the latest Javascript
libraries and not be susceptible to vulnerabilities when loaded in a
web browser. Content in the user's guide in general also needs to be considered from the point of view of not giving an attacker details about how the product could be configured for use in other scenarios other than the ones intended by the developers. |
| Server Side Validation | Validation and automated tests run on the server side (we use a Jenkins integration server) whenever changes are made to source code for a certain project. If automatic tests fail, emails are sent to the people who have committed the latest changes that broke the builds. | Whenever you have multiple topic files, filters, or content reuse, you may end up with potential validation problems in the edited content, problems ranging from broken links to invalid ID attribute values or invalid topics. Oxygen has a very useful Validate and check for completeness action that checks lots of potential problems in the context of a DITA map, but maybe not all people run such an action before they commit. Such an action can also be scripted to run on the server side in an integration server like Jenkins, for example. |
| Terminology | There are lots of ways that a message can be conveyed. All messages presented to the end user need to have a certain style, tone, and use plain language. | Controlled terminology is also an important aspect of a technical writer's job. |
| Translation | In general, all user interface strings in an application will be translated to multiple languages so we need to take this into account when designing the application. | A DITA XML project that needs to be translated into multiple languages also needs to follow a sequence of best practices. |
| User's Point of View | All features need to be discussed and implemented from the point of view of the people who will actually benefit from using them. For technical people, this is sometimes difficult to do but we try to constantly remind ourselves to implement features that help certain real-world workflows to be performed by the end user and not for the sake of closing tickets. | The documentation also needs to target certain user profiles and be written to help people perform tasks and understand concepts. The product knowledge level of the end user is almost never the same as that of the tech writer. |
| User Feedback | It's important to get feedback from end users. This feedback gives us ideas about what to implement in the future and also allows us to modify existing features to better accommodate certain workflows. So, we try to make it as easy as possible to give feedback, we have a Report problem action directly in the application, we have a support email address, a forum, user's list, and on each of our user's manual pages, there is also a feedback comments section. | Receiving user feedback for the written documentation is also very important to improve the documentation to cover the actual user needs. For example, the Oxygen Feedback platform can be easily embedded in the generated web pages to allow users to provide feedback related to the documentation. We use it for the Oxygen user's manual, blog, and it's a very good mechanism to get in touch with users and to improve the docs. |
| User Interface | An application may work very well from the functionality point of view but if it does not look very nice (ugly color theme, ugly icons, not intuitive user interface layouts) it will not end up getting used very much. | A published user's guide also needs to have appropriate colors and fonts to improve readability and find ability. So, besides the actual content care, decisions must also be made in terms of what font styles and sizes to use, or what color theme to implement. |
| Version Control | We use a mix of Git repositories and Subversion repositories for our software projects. Version control allows us to collaborate, to have a history of changes, and to have release branches for our products. | Using a version control system like Git similarly gives the
possibility to collaborate on documentation projects with various
workflows. As an alternative, you can use a commercial content management system or in the cloud editing solution. No matter what storage system you use to collaborate, having a history of changes and release branches is a must. |
| Working with AI tools | Developers can work with ChatGPT to ask advice about how to write various pieces of code, especially in programming languages that they are not familiar with. They can also ask for help re-writing messages or translating small pieces of content. | Working directly with AI tools or using an add-on like the Oxygen AI Positron Assistant view, tech doc writers can also use the AI tools to improve readability, remove grammar problems, re-write content in various styles, or translate content. So, AI tools are valuable for writers as co-pilots. |
Writers and software engineers have lots of things in common because we are all working with language and we communicate in a specific language. Computer programming languages contain less words and are more simple than the English vocabulary, but in the end we are all in the market of describing, expressing, and building large systems using simple terms.
If you have feedback about these concepts and how they influence your writing, it is as usual, welcomed.