Sarah Maddox's Blog, page 11

A tech writer, a map, and an app – ASTC 2017

I’m attending the Technical Communicators Conference 2017, which is the annual conference of the Australian Society for Technical Communication (ASTC). This post is about the session I presented at the conference.

I presented a session called A tech writer, a map, and an app. The session is about my experiences developing an app, why I tried my hand at app development, and what I learned from the experience. The app itself, Tech Comm on a Map, is an interactive map that shows events of interest to technical communicators. The app is available on the web and on Android.

The presentation included a technical overview of the app and what went into developing it:

The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
The difference between a web-based application and a mobile app. Tech Comm on a Map is available as a native Android app as well as a webapp.
Where the app’s data is stored, and how it’s crowd sourced.
What open sourcing means, and why you may want to open source your code.
The information sources that I used when developing the app.

I’ve learned much from the experience of developing an app, including:

Interactions with my engineering colleagues have increased mutual understanding and respect.
Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
Developing an app has helped me better understand my audience of software engineers, by experiencing their needs and problems first hand.
The project has given me confidence in my own abilities in a highly technical field.

The slides for my presentation are available on SlideShare: A tech writer, a map, and an app. You can also read more about the app, Tech Comm on a Map.

Customising Microsoft Word – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Rhonda Bracey presented a session called Customising Microsoft Word to increase your efficiency.  Rhonda uses Microsoft Word extensively in her role as editor, and is an expert on customising Word to suit your workflow. It was great to attend such an authoritative, well-structured session.

I didn’t take notes from this session, because it was directly after my own presentation and I needed time to recover.

Collaborating with developers – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Dave Gash presented a session titled Collaborating with Developers: Challenge Accepted! I love Dave’s talks because they’re always lively, and never quite what you expect.

Dave started by saying that developers aren’t that good at writing documentation. They don’t know the syntax. It’s not that they can’t follow the rules of syntax – they do that in their day job. They’re experts in a different syntax: code.

Dave’s hint is: Don’t waste your time trying to teach the developers to write properly. Instead, fix it and move on. Technical documentation almost always starts with content provided by developers. They’re the subject matter experts, and the content is likely to be technically accurate, but their focus is different from ours.

Content written by developers has some common traits, which Dave discussed in detail:

Assume too much knowledge.
Dive into code too quickly.
Branch off into esoterica—by which Dave means that they present clever and correct, but awkwardly atypical, usage examples.

Instead of trying to persuade developers to write better English, figure out how to collaborate with them. Use their content, and write what’s missing. Make their content presentable.

Some of Dave’s tips for collaborating with developers:

Do your preparation, and make sure they know how much you know. Otherwise they’ll assume you know a lot.
Meet them in person. Email and other non-direct forms of communication can waste a lot of time.
Be friendly and positive right from the start. Establish common ground and make sure they know you’re interested.
Ask open-ended questions, to prompt the developer to give background information.
Be the student, but ask smart questions and show you’ve done your research.
Ask the developer a question to which you already know the answer. This will help you gauge the type of answers they’ll give.

Dave gave a number of additional tips that I haven’t captured here. Thanks Dave for an informative and entertaining session!

Get your words in order – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Sonja McShane presented a session titled Get your words in order. She started by saying her presentation is kind of a list of pet peeves.

Sonja started out with a quotation about the order of adjectives in English. [Note from Sarah: You can find the quotation in the tweet from Matthew Anderson, as shown in this news item from the BBC.] Then she described best practices for the order of words in step-by-step instructions, in cross references, and in other sentence types that occur in technical documentation.

The presentation included tips on the following topics:

Apostrophes – know the rules
Punctuation of run-on sentences – ensure clarity and brevity
Articles (the, a, an) – use whenever possible
Pronouns – avoid whenever possible, and use the noun instead
Unnecessary words – delete them
Singular or plural – choose one and stick with it
“Every day” versus “everyday” – the second is an adjective/advert
Tense – use the present rather than the future tense
Bulleted lists – keep them simple

This was a fun session, because Sonja’s examples generated plenty of animated discussion. As one of the attendees remarked, we could have gone on fixing the sentences all day. A member of the audience also brought up the distinction between common usage and prescriptive editing. Another audience member pointed out that in conversation and texting, your brain just sorts everything out and doesn’t bother about the irregularities. The difficulty comes when you’re in a more formal environment and need to write more concisely.

Thanks Sonja!

[image error]

Bootstrap – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Grant Noble presented a session titled Bootstrap. The talk is about Bootstrap, and how it can help us with website design.

Grant discovered Boostrap through his hobby of homebrewing. He needed to keep track of his brewing processes, ingredients, and experiments. So, he developed an application to do that. Along the way, he discovered that his initial app design looked terrible on a mobile device. Looking for information on responsive web design, he discovered Bootstrap.

Grant’s talk covered the following topics:

An overview of Bootstrap
Why we would use it
Setting up Bootstrap
Containers, rows, and columns – the three fundamental things you need to know if you want to use Bootstrap
Examples
Bootstrap v4 beta – an upcoming new version, whereas v3 is the current stable release
Arguments against using Bootstrap
Alternatives to Bootstrap

What is Bootstrap and why would you use it?

Bootstrap is a framework for developing responsive, mobile-first websites. It provides the HTML and CSS templates you need, and JavaScript plugins for dynamic features like dropdowns and tabs. The “mobile first” part means you develop for small devices first, then scale up to larger devices like desktops.

Grant says a highlight is that Bootstrap makes your website look professional, and it requires only a basic knowledge of HTML and CSS. It gives you a responsive design, so your content looks right on all browsers and devices. It includes many themes and templates. And it’s free.

Setting it up

Grant walked us through the four basic steps of including Bootstrap in your website. Basically, it involves including HTML tags in your page headers to pull in the CSS, and tag, to make sure things work well on mobile devices. Also, make sure your page is HTML5 as defined by your html tag.

Containers, rows, and columns

Containers wrap your content. You can choose a fixed-width container, or a fluid container, depending on your requirements. To specify a container, you use a CSS class called “container” or “container-fluid”.

Rows fit inside containers, and columns fit inside rows. There’s a max of 12 columns per row. And again, “row” and “col” are CSS classes.

So, for example, you may have a with a class of “container-fluid”, and within that a further set of elements with classes of “row” and “col”. Instead of , you can use other HTML elements, including HTML5 elements.

Columns can sit side by side, or stack on top of each other, depending on the device size and ratio, as determined by the column styles you’ve specified.

Grant showed us examples of the various “col” classes, the resulting device sizes that you can cater for, and how you can use them to make sure your column is displayed in a useful, logical structure on all device formats.

There’s also a “table” class that produces a pleasing variety of responsive tables. And some classes that provide good-looking forms.

Bootstrap v4

Bootstrap v4 is in beta, and is a major rewrite. Grant recommends staying with v3 for corporate projects, or if you need to support older browsers. Otherwise, move to v4 so that you don’t need to migrate later.

Arguments against Bootstrap, and alternatives

People say: Sites using Bootstrap all look the same. You end up with a lot of tags and CSS classes. The CSS and JavaScript can make the page slow to load.

Alternative frameworks include Foundation and Skeleton.

Thanks Grant for a useful overview of an exciting framework.

[image error]

Structuring content – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Margaret Hassall presented a session called Structuring content – why, what, when, how, where. Margaret’s talk was a case study of the challenges her team has faced, and the techniques they’ve ysed, in putting structure around technical documentation.

Margaret talked about:

the tech writing team,
the development teams,
document and content types,
problems,
challenges and tools,
waterfall and agile, and
organisational restructures.

The teams

Margaret works for a large company, with about 15,000 employees around the world. It’s a tech-heavy company, using software to manage the business and provide services and products to customers. The tech writers create the user guides and reference docs for the apps. Five years ago, things were relatively simple. They had a team of five writers, and each writer would manage a particular release.

Then everything changed: delivery to far more channels, agile processes, changes to team reporting structures. The result was that developers needed to know a lot more, and the content held in people’s heads was lost. There were many more releases.

The tech writering team had to find new ways of doing things.

To measure the sophistication of their processes, the  team used the methodology recommended by Joanne Hackos: the information process maturity model. You assess your processes using the following scale, which moves from rudimentary through to sophisticated:

initial
managed
defined
quantitively managed
optimising

Margaret discussed how the team placed themselves in the above scale initially (somewhere between levels 1 and 2), and worked to move themselves up the scale.

The problems

Challenges included:

Where to store documents, given the move to greater globalisation resulting from the company restructure.
How to help people find the information that had been created.
How to manage and communicate the team’s priorities, given the organisational change.

The team conducted a survey of the users and content – find out who uses what, and audit your information to find out where it’s created. Margaret recommends this as a very important thing to do. For example, you may find that too much information is stored in email, which makes it hard to find for people outside the immediate team (such as the tech writers). You may also find that people need help with versioning documents. Different groups owned the various documents. Different teams preferred different tools, though Margaret says this is one of the minor problems. You can create macros, for example, to convert convert from one tool to another.

People often don’t realise that their content is valuable to other teams. For example, if you’re a research and development company, you need to create a specific type of content, to qualify for an R&D tax concession. Sometimes people don’t think their processes are important, whereas the content may be invaluable for the R&D claim.

Tackling the problems

Margaret’s team started work putting structure around the content. She discussed the following aspects of the changes and processes they’re putting in place:

Using and promoting templates – their importance, and how to be flexible but not too flexible.
Helping other teams organise content, particularly in tools such as SharePoint.
Getting access to the tools that other teams use, such as task-management tools (like TFS) to get the information stored in those tools.
Moving from a content creation role to a content curator role.
Also moving towards documenting processes rather than applications.
And doing more technical work, such as automating the publishing process.
Creating new content types, like videos and webinars.
Merging into the same team as the trainers.

New directions the team is taking:

Consider changing the name of the role from “technical writer” to something else. They haven’t yet come up with a new name.
Manage the sharing of knowledge.
Talk to developers at the water coolers.
Create guidelines and templates for developers to use. These also include glossaries and guidelines on document types, tagging and metadata.
Act as content editors.
Automate where possible.

In summary, Margaret said that the technical writers need to be more “technical” than before. She listed the new competencies the writers need, and a focus on automation and single source.

Thanks to Margaret for a great narration of your ongoing journey towards content structure.

[image error]

Ten terms you thought you understood – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Tony Self presented a session called Ten terms you thought you understood. It was an entertaining, information-rich presentation, as usual from Tony. His theme was that our role as technical writer change as quickly as the technology that we’re writing about.

As tech writers, we cope with new techniques, new delivery technologies, reducing time and budget, and other changes. Tony covered the following terms related to recent changes in our role. He discussed the meanings of each term, and the relevant advantages or disadvantages of the related technology or methodology:

L10n, i18n, g11n – localisation, internationalisation, and globalisation
SVG – a vector graphics format that’s stored as XML
DITA and S1000D

(Dave Gash remarked at this point that S1000D no doubt indicates a word of 1,002 characters, starting with S and ending with D)
STE – a limited vocabulary for technical documents, used widely in aerospace and defence industries

The following are terms we may think we know, but possibly don’t. For example, terms may have changed in meaning:

XUL and XAML – XML specialised for graphical user interface design
Page – this term has changed in meaning over the last 20 years, from a printed page to a web page, PDF, ebook, mobile platforms, and so on. This makes it hard to define the size of a page, for example, or its relative dimensions.
Screen and monitor – it’s hard to define the difference between these two terms. They mean different things in different industries, and the definitions have changed over time.
Pixel – this term is also shifting, due to different platforms, particularly mobile devices. Mobile devices have a high density of pixels (that is, a high resolution), which means the physical pixel is very small. So a mobile device may use four physical pixels to represent one pixel in an image. We therefore talk about physical pixels and logical pixels, to cater for the demands of hardware, and the need to provide people with a conceptual concept to work with.
RWD – responsive web design, a technique for designing web pages to appear appropriately on the different platforms (desktop, mobile, and so on).
Width – the width of a page needs to adjust for the device on which it’s being displayed.
Viewport – the area of a page that the reader can see at any one time. That is, the visible portion on a mobile device, for example.
HUD – a head-up display, such as a transparent display on a car windscreen projecting directions. You look through the HUD to see the road in front of you. There’s a mobile app that you can use to mimic a HUD using your mobile phone! Just put the phone on your dashboard so that its screen is reflected on the windscreen. So, we as tech writers need to know how to publish content to a HUD.
BYOD – bring your own device. Many workplaces allow employees to bring in their own computing device to work on. People walk around with many computing devices, including laptops, phones, etc. Tech communicators need to write content for multiple devices. The concept of SOE (standard operating environment) is losing power.
We also raced through RSS, SCORM, HTML5, CSS3,
And transclusion, conref (not really good terms for dinner-party conversation, said Tony), transformation, prettify,

Tony emphasised the versatility of XML formats in general. Because they’re text-based, you can edit the text, and translate terms that are visible to the reader. The text is also easily searchable.

How can we keep up to date with all this terminology and technology? The presentation included some tips, such as attending this conference. reading blogs, attending courses, and so on. We should experiment with these things, and share our knowledge.

Thanks Tony for an informative talk! One piece of feedback: There were more than ten terms.

How to be a newbie – getting started in a complex new field

I’m starting out on a new role. Still a technical writer, still at the same company, but on a new product, working with a new group of people and a new set of docs. Here are some of my thoughts on getting started in a complex new field.

I’m reading everything I can about my new field, and watching the videos that’ll help me figure out what it’s about. As a technical writer, I’ll soon be immersed in both the technical and the theoretical side of the field. But before that immersion happens, it’s good to find out how people out there in the world are using the technology. The applications where they’re putting it to use. The functions they expect it to perform.

In my case, the new field is machine learning. That’s a big change from my previous role, documenting maps APIs. I loved working on the maps APIs, and now I’m super excited to learn something new.

Noting the new concepts and terminology

As I read articles and watch videos, I’m making notes of the things that puzzle me or are new to me: concepts, terms, methodologies, technologies. These notes may become part of the docs I write, or they may turn out to be useful only to me. They’re valuable, because I’m currently acting as a first-time reader in the field. Later I’ll forget what I didn’t know. It’ll be harder to put myself in a newbie’s shoes.

For example, watching this video about machine learning, I found I needed a new definition of the term “vector”. The video used the term in a way that was unfamiliar to me. I found some help on Stack Overflow. (It turns out that, in simple terms, a vector in machine learning is a series of values, which you can think of as a row in a table.) I made a note of the term and its meaning, in case I decide to add a glossary in the docs.

Discovering the audience

At this time, I didn’t have a good feel for the intended audience. Perhaps the intended audience for the documentation would already know the term that I hadn’t understood. But it did no harm to make a note. In fact, it helped solidify my own understanding of the term.

While reading, I’m looking to get a feel for the various types of audience in the field. This will help me narrow down the audience for the docs. What types of experts are there out in the world? In the case of machine learning, there’s a diverse audience, all the way from machine learning scientists who design the training/inference models, through data scientists who know all about data and want to try machine learning as a new way of gaining insights from the data, and application programmers who don’t know anything about machine learning and just want to use a specific application of it in their app.

Figuring out the workflow

When I first started learning the field, I didn’t look at my own organisation’s existing docs for this range of products. Instead, I immersed myself in what the world out there is doing. What’s the typical workflow that people are talking about and trying to implement? Later, I’ll look at how our own products fit into that workflow, and how our docs explain the flow.

Remembering that things change fast in technology

If you’re moving to a new project with an existing doc set, take into account that things were probably different when the doc set was created. Perhaps the audience has moved on since the early days in that particular field. Perhaps most of your readers now know more about the topic than they did when the docs were written. This is particularly relevant if the technology was new when the docs were written.

Perhaps the readers are using a different set of terminology now. People may have standardised on terms, while it’s possible the docs have not kept up.

As a new reader of the docs and a new entrant into the field, you’re in the best position to notice this kind of thing.

Something I learned while writing this post: newbie versus nooby

There’s a difference between a nooby and a newbie. I didn’t know that. I thought it was just a spelling difference. In fact, there are three terms: noob (or n00b), nooby, and newbie. A noob is a rather naive, some would say even stupid, person. This term is used particulary in the world of games. Nooby is an adjective referring to the type of (silly/annoying) thing a noob would do. A newbie is someone who is new to the field or area under discussion. It seems you don’t really want to be called a noob, whereas being a newbie is not a bad thing. At least newbies can spell!

How to write release notes

Release notes, sometimes called a changelog, let customers know when something’s happened in or to a product that could affect them. Various groups of people are involved in creating the release notes. Sometimes it’s hard to know what to include in the release notes. Here are some thoughts from me, after writing release notes for different types of products over the last few years.

The most important function of release notes is to let customers know that something has changed in the product, particularly when that something may affect the way the customer uses the product. The change may be a new feature in the product, an entirely new product, a change to the way the product works, a change to the way the customer uses the product, the removal of a feature, or even the deprecation of the entire product.

Examples of release notes

Atlassian creates comprehensive release notes for the major releases of each product, with graphics to illustrate the major features. For example, take a look at the Confluence 6.0 release notes. The minor releases list the issues resolved.

The Canvas release notes are full of information, including graphics to illustrate the top updates.

Release notes at their most minimalist are often called a changelog. A good example is the page for the Google Maps Android API. For a major release, the team includes screenshots and a tutorial on the Google Maps APIs Blog as well as in the documentation.

Some products support a complex set of variations in platforms and languages, as you can see in the Debian release notes.

Chrome DevTools kick off their release notes with a video and plenty of graphics.

Who writes the release notes?

Often, a technical writer creates the release notes based on input from product managers, engineering teams, marketing advisers, and other stakeholders.

In other cases, a various teams write or contribute to the release notes. For example:

The engineering team may write the simpler release notes, such as minor releases (point releases) consisting of bug fixes.
Product managers or marketing managers create the content for major new features or product launches. This is particularly so if the organisation’s primary promotion channel is a blog. A case in point is the Google Maps APIs Blog, which I mentioned earlier in this post.
A developer relations team may write software samples that illustrate a new feature in an API, and a video illustrating the new capabilities.

Letting customers know about the release notes

It’s a good idea to ask how customers will discover your release notes. It’s unlikely they’ll come and check your site regularly, just to see if something’s happened.

Here are some of the ways you can let customers know that you’ve published new release notes:

Provide an RSS or Atom feed on your release notes. For example, the release notes page for the Google Maps JavaScript API provides an Atom feed, updated each time the release notes are updated.
Write a blog post about major updates and other happenings that your customers need to know about.
Offer email subscriptions for your release notes and other product news.
Set up social media accounts for your organisation, and announce product news via those accounts. This tactic is useful if you know where your customers are likely to see the news. Examples are Twitter, Facebook, Reddit, Instagram, and more. For an example of indepth use of a particular platform, take a look at my post on using Twitter as medium for release notes.

An important point is to make sure there are links to the technical documentation from the release notes, blog, Twitter, and so on. The links help customers find the information they need after reading an overview of the new features/products. The links also boost the search engine optimisation (SEO) of the documentation, and let the customers know the docs exist as a good source of information.

What to include in the release notes

New features and products. Let people know about new features that enhance their use of the product. Provide an information-rich summary of what the feature means to the user, and how they can start using it. An illustration is good idea. Depending on the product, the illustration could be a screenshot, a photograph or video, a diagram, or a code sample. Also include a link to the documentation where people can find more information. If the feature was requested by customers and the feature request is publicly visible, link to it so people can see you’re listening to their requests.

Bug fixes. Include a list of the issues fixed in this release. Link to the documentation for further information where relevant. If the bug report is publicly visible, link to it so people can see you’re responding to their reports of problems.

Upgrade guide. Note any steps people need to take when moving from the older release to the newer release of the product. In some cases, there may be significant steps required. The nature of those steps depends on the type of product. For example, if the product is an API, the developers using the API may need to change their code. If the product is a software application, the system administrators may need to adjust configurations and update other applications that interface with or integrate into the updated application.

Deprecations and turn downs. Highlight any product and feature deprecations, and let people know when a product is turned down for good. A deprecation is a notice to customers that a feature or product is no longer recommended for use, and will or may be taken down at some point in the future. If there’s an alternative product or feature, let customers know where to find information about it. If possible, provide a migration guide telling people how to move from the deprecated feature to the new feature.

Other notes. Put yourself in the shoes of the user, and add the information you’d find useful. These notes may come from UX testing of the new feature, internal testing of the upgrade process, knowledge of customers’ procedures from the technical support engineers, or other sources.

Is a template useful for the release notes?

You could consider creating a template, to ensure that each update to the release notes follows a common pattern. Often though, the previous set of release notes is a good enough guide.

A template may also be a good idea for collecting information from stakeholders, but beware the content bloat that happens when people feel they need to supply words to fill a gap. Release notes should be lean and information rich.

More?

That’s about all I can come up with for now. Do you have any thoughts?

Publishing a paperback on Kindle Direct Publishing

The printed copy of my book has arrived! That’s a good reason to talk about publishing a paperback via Amazon’s Kindle Direct Publishing.

First, the long-awaited arrival of a printed copy of my book, A Word If You Please. I published the book on Amazon.com in Kindle and paperback formats. Being all the way down here in Australia, it was a couple of weeks before my hard copy arrived. And now, here it is:

[image error]    [image error]

It’s about an action hero, Trilby Trench, who also happens to be a technical writer. Does her way with words bring the danger to her or does it save her from further troubles? Only Trilby can tell you that.

Publishing a paperback on KDP

It’s been a while since I last ventured into the online tools provided by Kindle Direct Publishing. I’ve previously published two novels in Kindle format.

It was a very pleasant surprise that you can now create and publish a paperback version of your book. When I last published via Kindle Direct Publishing, only the Kindle format was available. The cost model for the paperback format is print on demand: You pay Amazon a fee for each copy that someone buys.

I loved the online cover designer. You can choose your design from a range of templates. There are different templates for Kindle ebook and paperback. Upload your image, customise the colours and fonts, and submit the design.

Only one thing didn’t work quite as expected. When you publish both a Kindle version and a paperback version of the same book, they start off as separate books on Amazon.com. It’s a good idea to get them linked, so people looking at the book online can see that both formats are available. The linking is supposed to happen automatically, based on identical title, author, and some other metadata. The auto-linkage didn’t happen for me, so I contacted the Kindle Direct Publishing help desk. They replied to my request within a few hours, and the update came through within 24 hours. Excellent service!

It’s worth spending some time reading the Kindle Direct Publishing documentation, to figure out how to upload and format your content. I decided to use straight HTML for the paperback version of my book. If you go that route, you may find this article useful: How to make an Amazon Kindle book using HTML and CSS. The author of that blog post has recently posted a disclaimer saying the post is out of date. Even so, I found the overview useful, and the downloadable set of sample files too.