ASTC Conference 2021

Structuring Agile sprints to support documentation

 

Ever wondered how technical writing fits into Agile so that technical communicators don't get crunched at the end of every sprint? The truth is that every project is different and, therefore, requires different solutions. In this presentation, Kylie Weaver, founder of Clearly Focused Agile Communications, gave a quick Agile refresher, then looked at three ways to set up your sprints to help create the elusive conditions needed for a smooth and sustainable cadence with fast and efficient continuous delivery. 

​

A DITA content management system in action

​

Content Management Systems (CMS) have progressed in recent years to take advantage of the Cloud, richer Web-based user experience, APIs, and distributed databases. In the more specialised content CMS (CCMS) favoured by many documentation professionals, the same progression is obvious.

​

In this session, Dr Tony Self, Managing Director of HyperWrite Pty Ltd, introduced us to this new generation of documentation tools, through the Web-based DITA CCMS called easyDITA. EasyDITA leverages the power of XML databases, WebDAV, APIs and a rich user interface to provide a comfortable and powerful authoring environment. There's no code in sight and editing is done in a collaborative environment similar to Google Docs. EasyDITA provides an insight into how future authoring systems will work.

 

Tony's session covered:

• The difference between CMS and CCMS

• How the easyDITA CCMS provides a Web-based authoring environment

• The similarities and differences between Google Docs and easyDITA collaborative environments

• How file management and “referential integrity” works in a CCMS

• How document outputs can be created entirely within a Web-based environment

• The importance of integration to systems working with standards.

​​

Case Study: DocuZENtation

​

Averil Robertson, the Program Lead for Engineering Documentation at Zendesk, presented the internal engineering documentation challenges at Zendesk and how they are attempting to resolve them.

 

The session covered:

• The pain points around documentation in the Zendesk Engineering org.

• Zendesk's growth and the experience we want new engineers to have.

• Current state.

• Pilot program and feedback.

• Why we are using our own product, and the positives and negatives of that decision.

• What we're focusing on now and progress since January 2021.

• The tools and support we're putting in place to support content contributors.

• Developing a culture around documentation and being our own customer.

​​

FutureThink: Creating Sustainable Content

​

As writers, most of our effort focuses, and rightfully so, on the user. But in creating content, we also need to consider those who must later maintain that content -- our future selves!

​

In this session, David Gash demonstrated simple and effective ways to create content that is not only useful today, but can be updated later without a major hassle. Dave looked at several high- and low-level sustainability techniques you can easily apply to your content that future-you will thank present-you for! The session covered:

​

• The dos and don'ts of sustainable content

• How to identify problematic maintenance areas

• How to leverage simple code to ease later maintenance

• How to apply existing technologies to your advantage.

​

A Technical Showcase: Conversion from PDF to HTML

​

In this presentation, physics graduate, Riordan Byrne, provided a case study on the challenges in improving documentation at Intrepid Geophysics, a company that provides software and services for potential field geophysics, airborne electromagnetics and integrated geology. The company’s documentation, written in Framemaker, had the limitations that:

​

• Its 200+ documents were not easy to search, and limited to those users who had Adobe products

• The PDF documents, included with the software, didn't contribute to the company's online presence. A wasted potential in today's environment.

​​

The new format was Bootstrap 4 HTML. Javascript and Python assisted the migration and usability of a Framemaker-to-HTML published document library. Riordan explained the tools he used and the pain points that led him to improve his understanding of HTML, Javascript, GIT and the world of "open-source".

​

Alongside this major project, Riordan saw how documentation of API and languages could often be convoluted and mazelike. With some small tricks, he demonstrated how an API can become a pretty clear "picture".

​

The Vibe of XSL-T

​

The “S” in the initialism “XSL-T” is confusing because it stands for “Stylesheet”. But XSL-T is nothing like CSS, and is not much at all to do with what technical communicators would call stylesheets. In this presentation, Dr Tony Self demonstrated what XSL-T is, and how it is a powerful tool within the technical communication process. While technical communicators should not necessarily attempt to learn XSL-T, they should be very familiar with what it is capable of… the “vibe” of it. XSL-T enables “document engineering”, which many argue is the future of help systems, technical publications, and documentation more broadly.

 

In this session we learnt:

• Where XSL-T fits in the XML universe

• The difference between XSL-T and the two other XSLs

• What sort of things XSL-T can be used for

• What level of expertise is needed to work with XSL-T. 

​​

Why you may need Simplified Technical English in your toolkit

​

Simplified Technical English (STE) is the most widely used controlled language in the world. It started in the aviation industry in the early 80s, but it is now widely used by all branches of defence around the world. Other industries, not related to defence or aviation, have also started to use it. STE is also part of some software systems such as S1000D which is an international standard to produce technical publications in XML.

​

In this session, Dave Newdick, an accredited STE trainer, provided an introduction to STE and how it might affect your role as a technical communicator. STE has a set of writing rules and a dictionary. But you need training, relevant to your role, to set it up and use it correctly and efficiently. Dave covered:

​

• What STE is and is not

• Why you should know about STE

• What an example of STE looks like

• How to start using STE.

​

The freelancer's toolkit: a tour of project and business management software

​

As communication professionals, we use a range of tools to improve the quality of the content we produce. But how do you work out what technology is best to manage your projects and run your own business?

​

Presenter Peter Riches walked us through some of the software self-employed technical communicators can use in the execution of projects and administration of their business. He discussed a range of apps for Mac and PC, as well as the online tools that his company, Red Pony, employs.

​

Paragraphs versus bullet points

​

Both paragraphs and bullet points are important communication tools used for science and technical writing. However, incorrect and ad-hoc use of these tools can make life difficult for the reader. Dr Marina Hurley from Writing Clear Science presents clear guidelines to help you effectively design paragraphs and bullet-points and decide when to use them.

​

Let’s talk about style!

​

For more than a decade, Australian communication practitioners have clamoured for an update to the 2002 edition of the Style manual. Then in 2020, three major style references emerged:

​

• Australian Government Style Manual

• The Australian Style Guide™

• Australian Manual of Style

​​

Suddenly faced with the luxury of choice, which reference should technical communicators use?

​

Neil James of the Plain English Foundation, outlined the features of the Australian Style Guide™ and why the Foundation decided to publish the style content it developed over the 2 decades of writing and editing style guides for government and corporate organisations. The ASG reflects Australian writing practice for both print and digital environments. It provides clear and practical advice with just enough explanation to understand a style rule, how it has evolved and why it might have changed. It has an attractive and easy-to-use interface. And it’s free.

​