Why user documentation should be tested and how to do it

Everyone knows that it is important to test software so that you find any bugs before it goes out to customers. The majority of organisations that develop software have people who spend at least some of the time doing testing their software. Many may also do ‘user acceptance’ testing to check that the software meets [...]

Read Full Post »

Developing user documentation in an agile environment: An International Standard

UPDATE: The standard is now available: http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=43074 This week I gave a presentation with this title to the Technical Communication UK 2011 Conference. I’ve attached the slides that I used in the conference here: TCUK11_Agile, although they won’t really mean much to anyone! The majority of the presentations I’ve done in the past do rely on Power [...]

Read Full Post »

Working group 2 standards adopted by IEEE

This week two of the standards produced by working group 2, software and systems documentation, have been formally adopted by the IEEE and released as IEEE standards. The two standards are 26514 (Requirements for Designers and Developers of User Documentation) and my standard 26513 (Requirements for Testers and Reviewers of User Documentation). Best to visit [...]

Read Full Post »

Press release on my standard on testing and reviewing user documentation

I’ve just found this press release about my published international standard: IS0 26513 Systems and software engineering – Requirements for testers and reviewers of user documentation. It’s good to see press releases about standards to help our users find standards relevant to their business. The article also mentions the other standards that we are currently developing in [...]

Read Full Post »

Why ‘find and replace’ doesn’t work for documentation

I’ve been having a discussion today about a ‘behavior’ with some writers that annoys me. Situations often crop up with our documentation where a term or other phrase within the docs needs to be replaced with a different term or phrase. This usually occurs because of an update – something in the software changed name [...]

Read Full Post »

GUI elements and terminology

One thing I find that makes writing difficult is the confusing mass of terminology around GUI interface elements such as buttons, menus, pages, windows, tabs and so on. Many of the tools that I work with have standard elements that have standard names. For example in the Eclipse platform the main ones are workbench windows, perspectives, editors and [...]

Read Full Post »