Author Archives: Sarah Maddox

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.

Advertisements

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. 🙂 Instead, I sat back and enjoyed Rhonda’s presentation and demos.

You can find many of Rhonda’s tips on her Cybertext website. In particular, take a look at the Word category on that site.

 

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!

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 <link> tags in your page headers to pull in the CSS, and <script> tags to pull in some JavaScript libraries. You also need a viewport <meta> 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 <div> with a class of “container-fluid”, and within that a further set of <div> elements with classes of “row” and “col”. Instead of <div>, 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 <div> 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.

%d bloggers like this: