Blog Archives

Delete or remove?

What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.

Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.

An example is the model of users and groups. Let’s say the user arthurdent belongs to two groups: spacers and earthlings. When Arthur no longer lives on planet Earth, you would remove arthurdent from the earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username arthurdent.

Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2.  So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.

Delete or remove

Works for me. :) What do you think?

Introduction to API tech writing – upcoming webinar

On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.

The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!

APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.

Details of the webinar

Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.

The session covers the following topics:

  • What an API is and does.
  • Introduction to the role of API technical writer and our audience.
  • Overview of the types of developer products we may be asked to document – APIs and others.
  • Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more.
  • A couple of live demos of APIs that you can play with at home: a JavaScript API and a REST API.
  • Examples of good API documentation.
  • The components of API documentation, and the technical writer’s role in the creation of each component.
  • A day in the life of an API technical writer.
  • Tips on getting started in the role.

Here’s a link to the slides on SlideShare: API Technical Writing.

Introduction to API technical writing

More in the STC’s webinar series on API technical writing

Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.

I hope to “see” you at the webinar!

Webinar series on API tech writing, starting February 2015

The STC (Society for Technical Communication) is presenting a series of webinars (online seminars) on API technical writing, starting in February. I’m delighted to be presenting the first webinar in the series: Part 1: Introduction to API Technical Writing.

The role of API technical writer is exciting, rewarding, and challenging. In this webinar we’ll explore what an API is and does, see a couple of APIs in action (provided the demo gremlins stay away!), take a look at some examples of API documentation, and hear some tips on getting started in the role.

Details of the first webinar in the series

Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am here in Sydney!
Duration: One hour.
Fees and registration details: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.

Here’s an outline of the session:

  • Introduction to the role of API technical writer
  • Overview of the types of developer products we may be asked to document
  • What an API is and who uses it
  • A couple of live demos of APIs that you can play with at home
  • Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more
  • Examples of good API documentation
  • The components of API documentation, and the technical writer’s role in the creation of each component
  • Tips on getting started as an API technical writer

 Focus on APIs in the world of technical documentation

APIs are a hot topic in our field. Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.

Then there’s my upcoming API workshop in January (now fully subscribed) sponsored by the STC and Google. Tom Johnson runs an API workshop at TC Camp 2015. The September edition of Intercom focused on API technical writing. Tom Johnson has written some truly excellent blog posts on the subject over the last few months, the latest of which is a podcast with Joe Malin. Here’s a list of my own posts about APIs.

Are you into, or interested in, API tech writing?

Phew, a hot topic indeed. I’d love to know whether it’s something you’re interested in. Perhaps you’re dabbling in APIs, or already into them full time?

Bit rot in the documentation

This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. It’s a privilege to be here, and to speak at this cool get-together.

My session is called Bit Rot in the Docs. (The link goes to the slides on SlideShare.) The presentation looks at how documentation can degenerate over time, and some techniques for finding and fixing errors.

The very mention of bit rot will strike terror into an engineer’s heart. “Unused programs or features will often stop working after sufficient time has passed, even if ‘nothing has changed’.” (From the hacker’s Jargon File.)

Bit rot affects documentation too. Whether the cause be a changing environment, human error, or the infamous cosmic rays, we need to root out that rot. But should the technical writer read and test the documentation on a regular basis? That’s the least efficient and most error-prone way of detecting doc decay.

Instead, in this session we looked at the following techniques:

  • Automated testing of code samples.
  • Documentation reviews as a standard part of engineering team procedure.
  • Collaborative spot-testing.
  • Customer feedback.

For more details of the session, see the slides on SlideShare.

Bit Rot in the Docs

The DITA debate

I’m coming to the conclusion that there are specific types of content that suit a DITA environment, and that the converse is also true: DITA is not the best solution for every content type. (DITA is the Darwin Information Typing Architecture, an XML architecture for designing, writing, managing, and publishing information.)

“Well, duh,” you may say. :) I’ve never worked in a DITA environment, but I’ve attended two indepth training courses and a number of case studies that walked through successful DITA implementations. The most recent was at the ASTC (NSW) conference last week, where Gareth Oakes presented a case study of an automotive content management system that he designed and implemented in collaboration with Repco. The content is stored and managed in DITA format, and published on a website. (See my report on the session: Repco and DITA.) This was a convincing case study of a situation where DITA has succeeded very well.

In my analysis, the DITA implementations that work well are those where the content consists of a large number of topics, and where those topics have an identical structure. It’s almost as if you’re building a database of content. Good examples are catalogues of automotive spare parts, machine repair instructions,​ safety procedures, aircraft manufacturing manuals, and so on.

Apart from volume and support for a standard layout, this type of content has other requirements that DITA can satisfy well, including the ability to automatically build a variety of manuals by combining the topics into different configurations (via DITA maps) and multi-channel publishing.

On the other hand, some content doesn’t benefit much from such a highly structured storage format. Potentially, the overhead of a DITA environment is overkill and the costs may outweigh the benefits. If we have contributors to the docs who are not tech writers or developers, asking them to learn DITA or specific source control and editor rules can be a deterrent.

Dare I say it: Much of the documentation we write in the software industry falls into the latter category. Our topics tend to be lengthy, less uniform in structure, and more discursive than, say, an auto parts manual. API reference docs are an exception, but they’re auto-generated from software code anyway. We also don’t usually need to recombine the topics into different output configurations, such as different models of a car.

What do you think? Please contradict me. :) Do you have examples that gainsay or support the above conclusions? I’d love to see some examples of well-structured and well-presented documentation produced from DITA source.

Follow

Get every new post delivered to your Inbox.

Join 1,577 other followers

%d bloggers like this: