The curious case of Erskine May

Erskine May is the name of the book that describes the rules, conventions and procedures for the United Kingdom’s parliament. The book has become part of the uncodified constitution of the United Kingdom, and it is effectively the staff handbook for the Members of Parliament and the Lords. However, you’ll find very little about the Erskine May rules on the parliament’s website. Instead, if you want to know the rules on how parliament is run, you’ll need to buy it in book form, at a recommended retail price of £381.

The UK has been one of the pioneers of digital government, so I’ve often wondered why these rules haven’t published for the public to see them. From a conversation I had last week, I now understand the reason is because the copyright is held by the book publishers, and not Parliament, and there is little monetary incentive for the publishers to move the content online.

Let’s imagine the Parliamentary Digital Service were able to publish the information online (or even make the content available under the Open Government Licence). It would create the opportunity to make it easier for UK citizens, and even new MPs, to understand how parliament works.

It would also be possible to make it easier to find information, and filter information based on the type of MP or topic. Using metadata and semantic tagging, it would be possible to mark-up sections, by type of audience, topic or other criteria. For example, if all the procedures relating to Scotland were tagged, you could create filtered views or special navigations routes for the rules and procedures relating to Scottish-only matters. This tagging could be carried out by MPs themselves, or perhaps even crowd-sourced.

There could be flowcharts and checklists, to help people understand all the steps in a procedure. It could also help ensure these have been carried out.  It might also make it easier to identify area where parliamentary procedures could be improved, streamlined or simplified. It would be good for democracy, too.

 

7 March – Cherryleaf’s policies and procedures writing course

Cherryleaf’s policies and procedures course teaches your staff how to write clear and effective policies and procedures, in a straightforward and efficient way. It is popular with staff from charities and the NHS, although it will benefit many writers of policies and procedures.

Our next public course will be on the 6th March 2017.

See

Cherryleaf’s policies and procedures writing course

March dates: Advanced technical writing and new trends in technical communication training course

Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.

The next public classroom course will be held on Wednesday 29th March 2017 at our training centre in central London (WC2R).

For overseas clients, we will hold a class live over the web (on 22nd and 23rd March), if there sufficient interest.

See:

Advanced technical writing & new trends in technical communication training

 

Lessons from using a bullet journal: track as well as set goals

By Ellis

I’m experimenting with using a bullet journal this year, and it’s resulting in some useful ideas for managing and planning technical authoring work.

Setting and achieving targets at the start of the year can be difficult. You may end up needing to spend time on immediate, more pressing tasks, and your list of targets can end up feeling like a statement of the things you have failed to achieve.

One of the ways that people use bullet journals is to keep a track of their performance in a month. This is an example of a habits tracker by Kara Benz:

It works like Key Performance Indicators – you set the measures you want to track, and you record each time you carry out those activities.

By reviewing and reflecting each day or each week, on the things you have done, it helps you spot the items that are being neglected. It also seems to prompt you to do those tasks, like trimming a sail or moving a tiller.

It also encourages continuous growth, rather than proficiency. If you focus only on a target, there is the danger that you stop once you have met your goal. Focusing on achievements is also more positive, from a mental perspective.

You don’t, of course, need a bullet journal to make a tracking journal. You could use any notebook, a Word document, Excel spreadsheet etc.

If you use this method already, do share your experiences below.

Announcing Cherryleaf’s Communicating in Business newsletter

We’ve decided to create a new newsletter –  on communicating in business.

You can now subscribe to:

  1. The existing monthly Cherryleaf Update newsletter for technical documentation professionals on developing end user content.
  2. Our new Communicating in Business newsletter on developing policies and procedures, reports, marketing copy, and presenting data.

Both provide free advice and news on developing content. Your details won’t be shared with anyone, and you can un-subscribe at any time.

Farewell?

Adrian Warman has started a series of posts on his blog about the future of technical writing. In today’s post, Farewell to the technical writer, he argues the traditional role of a technical writer is no more:

“Marketing and sales specialists, designers, developers, developer advocates, support and operational people – indeed almost anyone associated with the overall creation and delivery of a service or product – are all perfectly capable of creating content that might not be perfect, but is good enough.”

There are many good points in Adrian’s post, and we look forward to the rest in this series. However, there is a counter argument to be made:

  1. Why do organisations still buy Flare or RoboHelp, when they could use Markdown? We would suggest it’s because projects often become more complex over time. You start to need support more than one version of a product (the professional and the standard version, for example); you need to support more than release version; you end up developing bespoke versions for your biggest customer; you need to localise the content for international markets. As the products become more complex, so can the documentation, and it can be a struggle to manage this complexity in an efficient way with Markdown.
  2. While the writing can be straightforward, the publishing process for Markdown content can be complex.
  3. If people have two responsibilities (code and write user content), one of those tasks may be not given the time and attention it needs. It might be better to have one person focusing on a single task.
  4. Only half the time in a documentation project is actually spent on writing. There’s a lot of planning and research that should go on before that into what users need from the content. Programmers may struggle with that aspect (although UX developers less so).
  5. A Technical Author might be cheaper than a programmer or a UX developer. If you can free their time, by delegating the writing activity to a Technical Author, you might enable them to focus on more productive activities.

The traditional role of a Technical Author is certainly changing, and there is likely to be a more collaborative authoring process. However, the Technical Author can still add value.

Review: Modern Technical Writing by Andrew Etter

Andrew Etter has written a short, Kindle ebook called “Modern Technical Writing: An Introduction to Software Documentation“. The book is Andrew’s personal view of technical communication, based on his experience of being a technical communicator in Silicon Valley.

It neatly describes the “Docs-like-code” approach to technical writing, and it challenges the impulse to write about everything. It describes Andrew’s experience of creating documentation in lightweight markup languages, such as ReStructured Text and Markdown, and using GitHub and static site generators to manage and publish the content.

Overall, I enjoyed reading the book. Andrew describes the benefits from following his approach. Ideally, I’d like to have seen more information and evidence to justify his opinions against other authoring tools. Microsoft Word might be a better choice than Markdown if you need to include complex images, tables or numbered lists. A Content Management System might be a better choice than a static website generator, if you want to provide intelligent content that modifies content to suit different users. The need to manage localised content (in multiple languages) might be easier to accomplish in DITA or MadCap Flare than by using GitHub and Markdown files.

Having said that, the book provides a useful insight into a increasingly common approach to documenting software applications.