Transition in Technical Documentation

By Shailendra Kumar

With the advent of the internet and new age companies, the significance of technical documentation and its alignment with software development has become a hot topic. This topic influences us to brainstorm how much documentation is enough and the role of technical communicators in the near future. In this article, we will touch upon these aspects to identify the challenges as well as the opportunities before the technical writing community.

Documentation will continue to play an important role in the life cycle of a software product. With advancements in Artificial Intelligence (AI), the documentation will be highly personalized and tailored to meet the requirements of end users.

How Much Documentation is Good Enough?

In the year 2001, a group of representatives from Extreme Programming, SCRUM, DSDM, Adaptive Software Development, Crystal, Feature-Driven Development, Pragmatic Programming, and others met to form an alternative to documentation-driven, heavy-weight software development processes.  An Agile ‘Software Development’ Manifesto resulted from that convention. Among one of the four values listed in this manifesto is ‘Working Software over Comprehensive Documentation’.

Per Agile principles, the documentation should be ‘just enough’ and developed ‘just-in-time’. Not only in the software industry but also in goods and services, voluminous user manuals are produced along with every product release. Let us take a simple example. As an owner of a vehicle, when was the last time, you opened the operations manual of the vehicle in case of an issue as trivial as a flat tire? With the advancements in information technology, the organizations need to think of better ways of educating customers on the usage of their products or services.

A well-designed product should come along with ‘zero documentation’. It is a pipe dream, especially for enterprise applications. With complex screens, terminologies, business processes, navigations, and embedded logic, it is not possible to use any enterprise business application without extensive documentation or implementation services from consulting companies. New internet-based companies have changed the game. Most of us never refer to a user manual when using a mobile application on our phones. We can argue that mobile applications can’t be compared in complexity with a business application, but the key is User Experience Design that can reduce the dependency of a customer on a set of documentation. The goal of documentation should be to keep it simple.

Using the Agile principles, the product documentation should be created based on the Personas of the users, and the aim should be to hide the necessary complexity based upon the knowledge and skill level of the users. Now let us address the question of ‘Just Enough’ documentation. Before we embark on the documentation exercise, we need to identify the target audience. In a business organization, the typical profile of users can fall under the following categories: Implementation Consultants, System Administrators, and End Users. Each of these users has specific needs of documentation, based on their roles and responsibilities. 

Persona-based Documentation

In business applications, a consultant’s role is to map the business requirements with the application functions and configure the application in an optimal manner. The documentation for consultants should focus on application setup, the configuration of business processes. On the other side, crisp and clear standard operating procedures should be good enough for end users. The system administrators being in-charge of the software systems, require more technical instructions including bug fixes, security setups, and performance management. In short, the scope of documentation should be restricted to the User Personas that interact with the system.

Alignment between Documentation and Agile Development

We live in an era of ever-changing business requirements that marked the shift from waterfall to agile methodology. The aim is to deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale. This practice puts tremendous pressure on technical writing to keep pace with the application development. There is a fundamental question: Should the technical publication be a part of agile teams or a shared services team?  The jury is out on this. Some may argue that technical writers can’t work in silos in a different department for requirements documents or updates about release cycles. On the other side, being a part of an agile team means attending all scrum ceremonies including daily standup meetings that are more useful for the development folks. The ideal setup depends upon the nature of the business operations. We can think of two predominant approaches, but the one that may be most effective could be the Hybrid approach.

Documentation Per Sprint

The related documentation is authored when the software feature is built. The release goal includes completion of the related documentation. There is no latency in documentation and the pairing of the technical writing resource with the sprint team. It means that requirements get documented properly and just in time with the release cadence. It can, however, be a resource intensive option depending upon the number of scrum teams.

Documentation Per Release

Documentation is planned for a specific release considering all the bundled features. This option is suitable for resource planning and tying the deliverables with the release cadence. The only drawback of this approach is the extensive follow-up and collaboration required with the development teams.

Documentation Plan in Sprints; Content Creation Per Release

Documentation and product release can be planned parallelly so that the technical writing team is aware of the features being developed. The content, however, is created per the release cadence.

Documentation Approaches: Pros & Cons

Role of Future Technical Writers

With the advent of technology, every role within a software development is undergoing a transformation, so will be the technical writing in the future. Before painting the future scenario, let us try to find the answer to the following questions:

  • Who will write documents in future – Developer, Product Owner, or Tech Writer?
    We are witnessing shorter and shorter release cycles. In this situation, the developer or the product owner or someone a part of sprint teams will be best suited to author documentation.
  • Who will review the content for style and language?
    Reviewing a document for language, grammar, and style is a specialized task that will be the forte of technical writers. The technical writers also have to ensure that the document is tailored to the needs of specific users from a usability perspective.
  • What type of documents will be required?
    With the increasing use of bots technology, the reliance on the use of standard operating procedures will reduce. Technical writers will be involved in creating innovative ways for customer interaction, which will eventually minimize the use of traditional documentation.

If we can distinguish authoring from styling of documentation, it may lead us to the future of technical writing. The most important question is about the skills required for future technical writing. The current content-authoring tools, for example, Adobe FrameMaker, RoboHelp, Arbortext Editor, MS Office, and many others will still be in vogue and there will be the advent of more powerful tools for authoring, reviewing, and publishing.

We can summarize by saying that in the agile world, technical writing can be more effective and contextual in order to keep pace with application development. To achieve this, technical writers will have to follow innovative operational models on the foundation of deeper collaboration with application development teams. This will require high adaptability at the organization and individual levels to learn newer technologies, ways of working, domain knowledge, and most importantly – how to work in teams.

About the Author

Shailendra Kumar

Shailendra Kumar is a product manager in a leading organization based in Hyderabad. Apart from making strategies related to Agile, IOT, and Big Data, his interests include writing and participating in long distance running.