Sunday 20 January 2019

Toward a universal Style Manual

The Australian Digital Transformation Agency plan to improve the Australia Government's writing style manual. Great. Can I help?

Worst user, best friend

I'll be your most demanding user. I'm technical, have no writing training and won't want to read the manual. And yet, this manual should be written for me. Why? Because people like me write policies, code, manuals, business cases, standards, designs,  requirements, tutorials. We write for government, industry, open source and international organisations.

Writers shouldn't read your manual

Auto-correctors fix spelling and grammar; templates help writers with headings and writing tips. The best way to reach us technical writers is to embed style guidance into these tools and templates. (Could you please also fix their formatting bugs, which seem to be in every word template I've ever used.) 

Go universal

Please avoid the temptation to create an Australian specific Style Manual. The inevitable inefficiencies caused by integrating local and international style variants will be painful. Draw inspiration from the Creative Commons licenses. They are internationally recognised, widely used and widely understood.  

Collaborate

Collaboration mitigates against being out-innovated, as in the digital economy, collaboration out competes competition. There are more smart people in the rest of the world, thinking about your problem, than can ever be mustered in your own team.
  • Use, extend, create - in that order:
    • Use existing material if it exists;
    • Otherwise extend and give back;
    • As a last resort, create your own.
  • Evangelise; encourage other nations to adopt the manual. Like language, the manual becomes more valuable as more people use it.
  • Use collaborative tools and methodologies to engage communities and evolve material.
  • Share ownership and control.

Modularity

Let's make the style manual extensible, to support domain specific requirements and individual flair. For instance, the international manual will need to support toggling between American and British spelling, and agencies will want to add domain specific acronyms. 

Don't finish

People will continue innovating. Establish a sustainable project, owned by multiple stakeholders, with periodic release cycles, which will last beyond your current funding cycle.

1 comment:

Cameron Shorter said...

This was published by The Mandarin.