The Art of Technical Writing for Software Engineers (ApacheCon Asia 2022)

The Art of Technical Writing: ApacheCon Asia 2022

7/11/2022

 By Matthew Sacks

Intended Reader 

Engineers and business managers are interested in learning the basics of technical documentation and how to implement it in their organization; however, also advanced documentation engineering topics will be covered towards the end of my presentation. 

About the Speaker

My name is Matthew Sacks, I am a systems administrator by trade for the past 17 years starting in 2005 as a network and systems administrator for MyLife.com (formerly reunion.com). I started as a junior network and systems administrator and was promoted to standard system administrator after one year of working in the data center and IT Operations department there. I had always done well in school for English exams and essays and had a knack for writing, so I took the skills I learned on the job and my curiosity for finding new software technologies and wrote my first published technical article on Splunk 1.0 for Sys Admin Magazine back in 2005.

I created documentation systems and implemented other technologies for the development team to use to collaborate more and faster, reducing the time it took to resolve issues and bugs in the code, as well as plan and specify new technologies to be implemented, and it always started with a proposal document or outline of what was to be implemented. I also contributed and helped start the USENIX Blog Team, which I believe is still in operation today (USENIX now has a robust regular blog), and contributed to other publications such as Linux Pro Magazine, ADMIN Magazine, InformIT, and other reputable online publications.

From there I worked in various Internet-based companies around Los Angeles such as Edmunds.com and Dun and Bradstreet. After working at Edmunds between that and Dun and Bradstreet, I wrote my first book on Web Development Operations (Web DevOps) which was published by Apress about how to function in an Operations team and reduce barriers to better work with development teams as an operations professional.

What you Will Learn

In this presentation, you will learn how to architecture software documentation, create documentation artfully, and design a documentation infrastructure.

Introduction

In my experiences as a systems administrator, I learned early on that having good technical documentation for the applications, systems, and networks that were being supported had a lot to do with the outcome of the success of the production support and engineering design of the software behind of all the organizations I worked at over the years.

In this presentation, you will learn how to set up a document and documentation infrastructure and the basics of technical writing, as well as more advanced topics such as document automation and product design specifications. 

Main Questions

Re: Why does art matter in technical or engineering writing?

Art matters in engineering because in the engineering and design process, you have to start with some kind of sketch or base framework before you start engineering, designing, and building any technology or software. Components of the whole document or product being built are inspired through artistic expression, and even the absence of art from a design or engineering document is a form of expression in and of itself. For example, the font I chose for this Word document where I am describing the elements of technical writing arts is called Calibri, which is a default Microsoft Office font. It is similar to Arial and doesn’t have much detail or style but it is simple and clean in design and easy to read; therefore, by choosing a certain font style, I have decided how readable my document is. This is where art comes into engineering and design and how it affects the way things are built.

How can technical writing be an art form?

Not only is technical writing an art form like poetry, stories, movie scripts, songs, or a new programming language or voice spoken language (linguistics), but it is an art that allows you to create functionality in life that previously was unavailable. Think about the Uber Eats app, when you go to open the app there is text to tell you that it is the Uber Eats app you are using. Next, there is the graphical user interface which allows you to touch and place orders and type your payment and address information to the app. Then there are the backend APIs at Uber Technologies Inc, that dispatch the request to a driver’s mobile app on the field. 

Every interaction that created this new functionality and mobile application that is the consumer-facing side of the technical infrastructure that supports and makes what Uber Eats is, is some kind of art form in the expression of functional code, graphics, and sound.

Before Uber Eats could be created though, there had to be some kind of design email or technical document produced that defined the patents and technologies, or the recipe for the code that had to be produced before you could order your burger delivered to your doorstep on your iPhone or Android phone.

Why do communication styles and artistic elements matter in terms of technical documentation?

Documentation is an art form because the way you write and arrange words and letters communicates differently when expressing complicated ideas such as the structures and compositions of code that make up software, and documentation is what supports the process of building the software.

You can write code without documentation, but without any structural reference to how the code was created, managed, and maintained. You may have difficulty performing those tasks with your code base. 

Each document and technical author will have their own style of writing and documenting software technologies, but when there are agreed-upon principles in an organization of how documentation is intended to be composed then it will make the code easier to produce and maintain. 

The Basics of Technical Writing 

The basics of technical writing include how to write API documents such as specifications, runbooks (how to operate your software), getting started guides, and being able to describe technical solutions in a format that makes sense to multiple audiences. The audiences you are writing for are software engineers, project managers, operations, and business/executive audiences when writing any technical document.

To write for multiple audiences it is important to structure every document with the following outline:

Intended audience: Here you describe what type of role the reader reading should be and what they would expect to receive from the document they are reading or implementing instructions from.

Almost any technical document should have the following features:

1. Purpose of Document – what are you going to gain from reading the document?
2. Intended reader – always write for multiple audiences depending on which types of audiences you believe will be reading and benefit from obtaining this information. 
3. Date and metadata (author, tags, etc) – Being able to be searched and organized by categories.

If your document does not contain these three things it may become difficult for wikis and indexing systems to categorize them properly and without a statement of purpose and description of who is to read the document it may be unclear as to why the document was created and to whom it is intended to address.

Some of the key points to address when writing technical documentation are as follows:

• Ensuring the document is easy to find.
• Ensuring it is well written, clear, and has a clear goal or outcome after reading it.
• Address assumptions of the reader (assess and let them know the intended skill level or coding level of the reader reading the document)
• Make it easy to find related content (recommendation engines)
• Writing for multiple audiences and addressing all of the intended readers.

(thanks Jarek Potiuk for your input)

Documentation and Aesthetics

Art is about visual communication, when you look at a DaVinci, Cezanne, or Matisse, each painting communicates a different emotion and/or visual message. If there is nothing else you learn from this talk please note this section as the most important message in my speech. When you study aesthetics and design as a writer, you will improve your technical writing skill. As you improve your writing skill, you will grow as an artist.

Every document has its own aesthetic style. The style which you discuss, design, and create will have a positive effect, if done correctly, throughout the lifetime of your organization. 

Common Documentation Systems  (Wikis)

• Confluence
• Dockuwiki
• Wiki.js (or js.wiki)
• SharePoint

The documentation system I first used when I was a technical writer was actually Microsoft Sharepoint, I believe. It had just been recently released in 2005 and it came with a lot of features for documentation infrastructure. Later on, I found that Confluence was my favorite option and integrated well with the other Atlassian Bug tracking and software engineering suite of tools. You could reference JIRA ticket numbers within your documentation and it would automatically create a link to the JIRA issue being referenced. I would recommend Confluence and the Atlassian suite of products as the most common and robust documentation infrastructure available for software teams, currently. Still, certainly, there are many open source and free alternative solutions for documentation infrastructure.

Setting up a Documentation Infrastructure for your Organization 

1. Identify which documentation system you want to use for your primary content or wiki. Do you want a paid solution, cloud solution, onsite, wiki, and bug tracking integration? You need to meet with your engineering team and come up with a wish list of what you want your documentation system to do better than the existing one, or if you are just starting out, which goals you want the documentation system to accomplish. I recommend Confluence or JS.Wiki in most cases. 
2. Define the minimally required information you need in all documents. There should be a defined structure of your documentation style and structure (through the use of templates or otherwise) that all members of an organization are required to follow. The intended reader, the purpose of the document, and metadata are all necessary minimal components of any documentation style definition in any organization.
3. Create Templates. Most documentation systems and wikis employ the use of templates. You can create a base template and integrate your organization’s defined documentation styles and minimum requirements into these templates for members of the organization to use and fill out the information so that your documentation maintains a consistent style throughout the organization.
4. Employ a technical writing editorial team. Whether you have dedicated technical writers on staff or appoint leads in charge of documentation efforts you should have an editorial review team and process defined such that when new documentation is released it is vetted and checked for errors and accuracy as you are operating potentially life-critical systems based on the documentation being used to power crucial software systems. 

Architecture Design Diagrams

Architecture and infrastructure design diagrams are crucial components of building and maintaining any software infrastructure. Whether it be a mobile app, an application server design specification, or a new web application or networking technology there must be some architectural design structure for how the code will be assembled and built from a high-level view. When you build a building, you must have some kind of established vision before you write a blueprint or build a three-dimensional model of the building you have in mind. It starts with a sketch. A graphic design. Graphic designers are a crucial element of information technology and software design. You will have to have some skill in assembling or drawing design diagrams in software technical writing. 

Product Design Specification

In this documentation example, we will cover how to build a software product from scratch; in this case a mobile application. Any software product will need to be specified in the documentation before it is built. Before you write any code or make any design there needs to be a document describing how the software or in this case a mobile app, will be built.

This is a high-level document, each component of this document may have a supporting document to further detail the various components of a new software product design. For example, backend infrastructure specifications here will be detailed at a high level; however, when it comes time to build the actual product it will have to be detailed with a supporting backend software architecture diagram.

UI

Here we define how the User Interface should be designed so that the design team can build the graphical user interface for the application or mobile application being created.

Backend Architecture

Here we define how the backend architecture will be built to support the web, mobile, or desktop application. This may include but is not limited to, servers, serverless containers, microservices, other types of containers, backend APIs, and services that support the customer-facing, or user-facing application interface.

Cloud architecture

Many technologies now utilize some kind of cloud computing platform. It’s important to indicate which cloud provider will be used, and the associated documents or sub-documents can detail how the cloud computing infrastructure will support your application infrastructure.

The cloud architecture will resemble backend infrastructure documentation and diagrams, but it is noted in the product design specification because many technologies now utilize some kind of cloud computing platform, so it is important to notate which cloud provider will be utilized and create associated or sub-documents that detail how the cloud computing infrastructure will be utilized to support your application infrastructure.

Interface

Every web, mobile, or desktop application has some way of interacting with and operating it; thus, when building a specification for this kind of application there needs to be a defined method of operating it in the product design specification.

The methods of operating your application may be, but are not limited to: voice command, keyboard input, and touch input or buttons/controls. This part of how the User Interface is going to be utilized is necessary to be well defined before building any application and may include user interaction mockup diagrams.

Monitoring and analytics:

Every application should have some defined method or API for gaining insights into how the application is being used by users and administrators. There need to be feedback mechanisms such as Google Analytics and/or Hotjar for Web apps, and Flurry Analytics or similar solutions for gaining insights into how the Mobile Application is being used once deployed to test or production.

Artificial Intelligence/Machine Learning Components:

This is not recently a necessary requirement of product design specifications; however, now with the growing advent of some kind of artificial intelligence or machine learning capability made by API services or libraries or by other means, it is now crucial to define what types and how the artificial intelligence may be used in your application and should be an integral component of all software documentation product designs going forward.

Diagramming

Creating diagrams is a crucial element in writing technical documentation for software. Some of the common tools you may use to draw documentation diagrams are Microsoft Visio, Adobe Illustrator, Adobe Photoshop, or even hand-drawn. We will briefly cover some of these tools and how they are used to create a network, system, software, and security architecture diagrams. 

1)     Visio – Microsoft Visio is an excellent tool for creating infrastructure and software architecture design diagrams as well as network architecture diagrams. Any diagram that relates to system or software infrastructure can be created using pre-made stencils for most platforms, operating systems, and network types. For example, AWS has its own set of stencils and Cisco has a set of stencils for networking that make it easy to draw and diagram your infrastructure.

2)     Illustrator – Adobe Illustrator is more of an art tool used for creating illustrations digitally from scratch but if you know how to draw in Illustrator you can make custom diagrams as well with a high level of detail.

3)     Balsamiq mockups is a cloud and desktop-based software that I find very useful for creating wireframes for building the structure and layout of web applications and mobile applications, but could also potentially be used for systems and networks as well.

The Developer Interview Format

In my work at the Bitsource, which was a software engineering blog I created back around the 2010s and traveled to many conferences around the country interviewing various software pioneers, I learned that the developer interview format is an effective way to discover information about the software that might not have any documentation in the first place. The discovery process is something that allows you to gain insights into how the existing code or software architecture is composed, and interviewing the developer or developers behind the code for your software can reveal insights into the inner workings and aspects of the code that might not be addressed in traditional documentation; thus, it may be crucial when releasing or redesigning software to conduct some kind of interview and get all of the questions out on the table for all of the different skill levels of the readers reading the interview. Once the interview is produced, oftentimes it will reveal new types of documentation that needs to be created to support your software and act as a reference point for more traditional types of documentation associated with the software being discussed. 

Feedback and Editorial Review

Every document should be reviewed by a professional technical editor or developer editor. With any first draft, there are usually grammatical issues, errors in code, and other problems that will prevent the document from being useful and error-free. Many technical editors can be outsourced on websites such as Upwork and Fiverr but depending on the needs of your organization it may be wise to employ an entire technical editorial team to help with documentation efforts in your organization as the role of a technical writer, editor, and manager is becoming more prevalent in all organizations IT departments. 

Automated Documentation Systems

I gave a talk at a USENIX LISA Conference about 10 years ago (the talk slides are no longer available online) about the need for automated documentation systems. At the time the only automated documentation systems were specifically for generating API docs without much comments or explanation using Javadoc or pydoc for Python code. Now, there are many automated documentation systems for many different programming languages and platforms, and there are some automated documentation features now appearing in IDEs and Orchestration systems.

I looked online and tested a few free trials for automated documentation systems and here is what I discovered. I cannot say I have fully evaluated any of these services or systems but I can say that they are worth further looking into for documentation automation systems.

 a

Archbee.io

This system uses markdown files, openapi files, github data, and other types of Wikis to update and generate documentation.

Documentation Automation for Teams | Light AI — Light Docs

Conclusion

Technical Documentation includes many aspects of how art is employed to create software technology by defining the building blocks of how the code is to be designed and built from the idea to the solution to being turned into actual code. The way your documentation systems and content are arranged and disseminated has a great impact on the success of your product roadmap and code quality. 

Advertisement