XML isn’t the only way to semantic content

I’ve been on the road speaking at a conference this week, and I’ve been listening to a lot of presentations on technical communication. Many of these were on the importance of having structured, semantic content when you are dealing with large amounts of content that needs to be translated into different languages and published in many different ways. All of these presentations put forward XML-based systems as the solution.

However, XML isn’t the only method for having semantic content. For example, AsciiDoc supports attributes, which can be used to add a semantic descriptions to headings, paragraphs and whole documents. You can use conditions in RoboHelp and Flare to categorise content. You can also store content in a database.

It’s sometimes useful to remember that XML isn’t the only way to semantic content.

 

Cherryleaf’s technical writing online training course has been re-accredited by the ISTC

Cherryleaf’s technical author basic/induction training course has been accredited by the Institute of Scientific and Technical Communicators since its launch. This accreditation has to be renewed every few years, which involves having the course is re-assessed by the ISTC’s accreditors. Earlier this year, we submitted the course for renewed accreditation, and we’ve recently received an email informing us the course has been approved again by the ISTC.

Americanisms and Britishisms

There are user documentation projects where we are asked to write in American English instead of British English, and generally this is a pretty straightforward exercise for us. However, when I speak at conferences in the USA, delegates sometimes ask me afterwards what I meant by a particular expression. For example, I was recently asked what I meant by “round the houses” and “cheesed off“.

There are a large number of subtle differences between the two versions of English, which has led to a number of very interesting blogs on this subject. In particular, Dr. Lynne Murphy’s Separated by a common language and Professor Ben Yagoda’s Not One-Off Britishisms blogs provide a fascinating insight into how words and expressions gain popularity. The Language Log is another blog worth reading.

If the move to a more conversational approach to technical writing grows in popularity, we may see these differences becoming a bigger factor in localis(z)ing to American or British English.

Technical writing as public service – Video

Here is a link to a recording of an interesting presentation from Britta Gustafson on aspects of working on documentation in the US Government.

“What if U.S. federal agencies decided to reuse and contribute to open source software projects built by other agencies, since agencies often have similar technology problems to solve? And what if they hired technical writers with open source community experience to write documentation for these projects? That would be pretty cool. Also, that’s my work.”

Technical writing as public service: working on open source in government

 

Update: The Internet of Things – creating a digital user guide to attach to a door

Following on from our post The Internet of Things – creating a user guide for a fridge door, we came across other ways to create e-ink digital user guides that could be attached to the door of meeting rooms, providing information on room bookings, using the equipment in the room etc.

Continue reading

The Language of Technical Communication book has been released

The Language of Technical Communication book is a collaborative effort with fifty-two contributors defining the terms that form the core of technical communication as it is practiced today. Cherryleaf’s Ellis Pratt was one of the contributors.

Each contributed term has a concise definition, an importance statement, and an essay that describes why technical communicators need to know that term.

61QTrFMxn1L

Customers as Advocates Conference 2016

I thought I’d mention a conference I’ll be attending this month – The Customers as Advocates Conference.

“Customers as Advocates” focuses on the challenges of creating successful customer relationships that lead to reference and case study programmes.”

Although it is aimed at professionals that sell and market enterprise technology, I found it very informative, as a great deal of it relates to User Assistance and other forms of technical communication.

I attended this (free) conference last year, and I particularly enjoyed the presentations on developing and nurturing a thriving community of advocates.

“More than 70 percent of the buying journey is complete before a customer looks at your marketing or engages with sales. Who are your prospects and customers speaking to, and what are they sharing about the experience?” Ian Williams, Director, Jericho Consulting

The conference will be held on Thursday 26 May, in London.

Microsoft launches its new documentation site, and it’s very good

Microsoft has announced the preview release of its documentation service, https://docs.microsoft.com, which currently provides content for its Enterprise Mobility products.

“We interviewed and surveyed hundreds of developers and IT Pros and sifted through your website feedback over the years on UserVoice. It was clear we needed to make a change and create a modern web experience for content…For years customers have told us to go beyond walls of text with feature-level content and help them implement solutions to their business problems.” (source)

The key features are:

  • Improved readability
    • “To improve content readability, we changed the site to have a set content width.”
    • “We’ve also increased the font size for the left navigation and the text itself.”
  • Including an estimated reading time
  • Adding a publication date
  • Improved navigation
    • It is now based around sections on evaluating, getting started, planning, deploying, managing and troubleshooting
  • Shortened article length per page
  • Responsive Web Design
  • Community contributions
    • “Every article has an Edit button that takes you to the source Markdown file in GitHub, where you can easily submit a pull request to fix or improve content.”
  • Feedback mechanisms
    • To provide comments and annotations on all of the articles
  • Friendly URLs
  • Website theming
    • You can change between a light and dark theme

Wow – this matches closely with the topics we cover in our Advanced technical writing & new trends in technical communication training course, where we look at the changes made by other organisations.

Although it doesn’t mention it in its announcement, Microsoft has also made changes to the style of its topic headings and content. There’s frequent use of words and phrases such as “protect”, “discover” and “understand and explore”.

We’ve yet to look at the site in detail, but initial impressions are very positive.

What do you think?