Creating DocOps engineers at Rocket Software
By Philip W. Stanley
Senior Information Architect, Rocket Software
Like many older people in technical writing, we didn't have college majors or courses for our technical writing careers. Coming from education, English, library sciences, and other courses of study, most of us fell into technical writing. We used the tools of the time, which limited us to writing and publishing content using the methods envisioned by the developers of those tools.
While using those tools, we often thought, "It would be great if we had a tool that did 'X,'" or "Why doesn't this tool do 'Y'?" Some technical writing teams had one writer who was a technophile, always tinkering beyond the tools of the trade. Whether it was Visual Basic for Applications, Visual Basic, C/C++, and later, Python and JavaScript, those writers would create solutions to meet the department's needs. These were the first Documentation Operations (DocOps) engineers.
While it is possible to contract a developer to code some tools your technical writing team needs, they usually don't have a technical writer's perspective to truly understand the project's needs or foresee potential hurdles. This leaves us with the question, "How do we get knowledgeable DocOps engineers to create solutions for our environment?" We must create them as few writers will do it themselves.
The first question that a technical writing team must ask is, "Can we lose the contribution of a writer to turn that person into a DocOps engineer?" Ask your team how often they do manual, repetitive tasks that could be automated or scripted and how long it takes. That amount of time provides the answer. Given that many companies and organizations emphasize career development for their employees, creating a DocOps engineer role provides another path beyond becoming a senior, lead, or principal technical writer.
Next, leaders must understand that training will take time and that the new DocOps engineer won't be able to code a Component Content Management System or an XML editor as their first contribution. Perhaps you need to change the value of a language attribute in thousands of DITA topics? Maybe you need to modify output generation for existing tools, such as rebranding? Do you need to convert a list of names and email addresses into a JSON, XML, or comma-separated values (CSV) file to upload to an existing tool? Also, will you need these tools regularly?
"How do we train a DocOps engineer?" It depends on the person's learning method; however, a project must guide the learning. If you need a script to convert a file in one format to another format, consider creating it with Python. If you need a web application, focus on a database, the virtual machines (VM) available in your organization, the operating system of the VM, and JavaScript.
While official documentation and training classes for these technologies can provide a foundation for understanding how to develop a solution, questions about specific scenarios, errors, or ideas can be found through Internet resources, especially www.stackoverflow.com.
Don't deny yourself the contributions of others. The Open Source movement has created a vast trove of libraries, tools, and utilities that can accomplish a lot of heavy lifting in creating a solution. Search engines, databases, converters, controlled language analyzers, web page tours, parsers, and many other tools are freely available. As time passes, the DocOps engineer will focus on more complex solutions, including automation, quality assurance, cloud resources, and real-time interoperability.
I was a technical writer for over 20 years. During that time, I created solutions for problems or needs that arose, both large and small, and taught myself whatever technologies were applicable or available, such as REXX, regular expressions, Python, JavaScript, JSON, YAML, utilities, SQL, HTML, XML, SGML, Elasticsearch, Amazon Web Services, web components, and many others. The more knowledge I gain, the more ideas I have on creating solutions for whatever comes our way. With over 50 writers in our Information Development department across the globe, Rocket Software has a team of three Information Architects that manage our content development and publishing platforms and create tools/utilities to increase productivity and quality.
Over the past two years, our team has developed or are developing solutions, including the following:
Various Python command line interface scripts for modifying DITA markup from acquisitions to conform to the standards of the organization
A Python CLI script for converting a Word document to a DITA bookmap and topics
A JavaScript-based tour for new visitors to the online documentation portal
An Elasticsearch-based documentation database to enter and track the details and history of customer documentation for more than 100 software products, including Kibana for data analytics
A controlled language utility, using Vale and spaCy, to analyze and report on content that does not conform to the organization style guide and common English grammar issues
A Python graphical application for analyzing all DITA topics in a directory tree and reporting problems across more than a dozen aspects, including long topics, short topics, short description issues, invalid external links, barred DITA elements, and more
A Python graphical application for converting the DITA markup of a two-column table to a definition list
We have a Slack channel where writers can contact the team immediately with questions or problems, and Information Architects can make announcements to the entire writing team and leadership. Writers can also use Jira to create tickets for the Information Architecture team for many administrative tasks and complex issues.
To summarize, not every tool or product you use in your content development environment will meet all your needs or do things as necessary for your specific situations. You can overcome these problems by hiring or training Documentation Operations engineers. They will understand the needs of technical writers and create solutions to increase efficiency, productivity, quality, and job satisfaction.
Philip W. Stanley
Philip W. Stanley is a senior information architect at Rocket Software with over 20 years of experience in technical writing and developing solutions for technical writing environments. He has mainly worked in the telecommunications and contact center industries, including Lucent Technologies, Avaya, Accenture, Verso Technologies, Interactive Intelligence, and Genesys. His main career interests are knowledge Management, cloud infrastructure, Information Experience (IX), and software development.