How to scalably support tens of thousands of pages of technical documentation related to complex hardware and software setups? Yordan Ugrinov, Content Operations and Engineering manager, talks about the current state of structured content authoring at VMware.
VMware is known for its cloud platform solutions and services. These solutions rely on well-documented instructions, which are delivered in product documentation, release notes, and other types of technical documentation. This documentation is created in-house by teams of technical writers, product managers, and engineers.
While traditionally technical documentation was developed by trained technical writers, growing organizational and product integration complexity created the need for direct involvement of developers, architects, and other subject matter expert (SME) roles in the creation of documentation. To meet the need, VMware adopted a strategy to democratize content creation and enable all employees to become authors.
Intuitive content creation process
Yordan and his team are responsible for the solutions and systems that are used to create technical content. The content is stored in SDL Tridion Docs and several other solutions, and edited using Fonto Editor and traditional desktop applications. For SMEs, the publication management and review workflows are managed in a web application that was developed by VMware.
In order to successfully introduce the concept of structured content to the SMEs at VMware, some authoring experience hurdles needed to be removed. Yordan names four examples:
- The team has integrated the documentation portal with the VMware Single Sign-on, which means VMware employees can contribute content and perform technical and editorial reviews by simply logging in with their VMware account.
Maintaining a second set of credentials is not feasible when you want to open authoring to everyone in the organization. That becomes even more important when you add collaborative documentation reviews to your workflow. Initial data from the Fonto Review adoption program shows that for every author there are three to five reviewers, depending on the publication.
- Fonto has been selected as an application to make structured content authoring user-friendly. By providing an interface, which is more or less similar to an ordinary word-processor, there is no need to understand complex DITA structures for the SMEs.
- Instead of going through the CMS interfaces to find the content that needs an update, any VMware employee will soon be able to launch Fonto Editor from the VMware Docs web portal and propose their changes for publication.
- The release notes authoring and reviewing application integrates the Fonto Editor and Fonto Review applications with the internal issue tracker in use. This allows seamless copying of content from issues, directly into the release notes document.
Review of content
With Fonto Review, VMware is able to run the review and sign-off process simultaneously. Authors can easily invite reviewers who will receive an email with a deep link to the specific section of the document which needs to be reviewed. For the reviewers it saves time because the content is just one click away, while the authors save time addressing the feedback by not having to go through several PDFs to extract comments manually. The dashboard provides a status overview, the number of comments, the due dates and the number of approvals.
This workflow contributes to the adaptation of the structured content authoring process. “User communities love it”, according to Yordan. No complex CMS or databases knowledge is required. Reviewers are fully enabled to do their job, without hassle or frustration.
Yordan and his team are preaching the advantages of working with structured content over unstructured content. One of the biggest advantages is content reuse.
Technical documentation about datacenter architectures for example contains a lot of combined information from deployment guides and example architecture documents. Up to 90% of the content can be reused, which provides a huge time saver. In a single datacenter dozens of products are integrated. In this context, it is crucial that information and guides are correct and up to date. This goes for product specific as well as version specific information. According to Yordan this can only be achieved by working with structured content.
“Some of the most complex documentation sets are created with Fonto”Yordan Ugrinov
The reuse of information is not limited to (technical) documentation. For marketing and sales departments the advantages of structured content are clear as well. Reuse of content and a smooth review process contribute to a higher level of efficiency in these departments: “Content creation is sliding from traditional content creation to structured content authoring.”
As VMware looks forward to furthering its collaborative authoring strategy, they hope to expand the adoption of the authoring system to other content groups across the company.