Using Markdown to create a boilerplate document for reports and proposals

Following on from our post Cutting and pasting content into Word documents – Is there a better way?, we’ve been looking at how organisations could use Markdown to create reports and proposals more quickly and consistently.

The objective was to:

  • Create something simple for non-technical people to use.
  • Have a collection of re-usable chunks of content that could be embedded into the document (no more cutting and pasting). If a chunk needed to be changed, then the documents where it is embedded would reflect that change automatically.
  • Be able to generate the completed report as a .docx (Microsoft Word) file.
  • Separate the content from the “look and feel”.
  • Enable different people to work on different sections of the document simultaneously.
  • Store the content in an open format, so there was potential to use some of the content in other places (such as on a website).

Continue reading “Using Markdown to create a boilerplate document for reports and proposals”

SharePoint for documentation projects

Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.

For all those issues, SharePoint may still have its place – for managing documentation projects.

Continue reading “SharePoint for documentation projects”

RoboHelp 11 review (finally)

robohelp logoAdobe released its latest version of RoboHelp Version 11 (and Technical Communications Suite 5), a while back and asked if we could write a review. There have been a number of excellent reviews, so we’ve been wondering what extra we can say. We’ve decided to address some of the questions we’re often asked by organisations when they’re deciding which Help Authoring Tool to choose.

Continue reading “RoboHelp 11 review (finally)”

Should Technical Authors be allowed to work from home?

With the recent media attention on Yahoo’s announcement that it is banning its staff from “remote” working, we thought it might be useful to look at the case for and against Technical Authors working from home.

The case for allowing remote working

  1. They can do their jobs more productively without interruption from others. When Technical Authors are writing (which is approximately 50% of their time), it can often help their concentration if they can work in a distraction-free environment.
  2. There’s less need for office space and related costs (telephones, desktop computers etc).
  3. Staff may be less stressed. Brad Harrington, executive director of the Boston College Center for Work & Family, claims people who work from home tend to have less stress and are more productive, partly because they don’t invest time and money in commuting, and they can have a better work/life balance.
  4. You may get more flexibility over staff availability. Without the need to commute, staff may be more willing to work out-of-hours.
  5. You have a wider pool of people interested in your vacancies if you can offer some flexibility in working hours and location.

The case against allowing remote working

  1. You’re more likely to build up a company culture if everyone is working in the same space together. This is particularly important for start-up businesses.
  2. It’s easier to network with others. These contacts could boost your careers in the future.
  3. It’s easier to monitor the work staff are carrying out.
  4. It’s can be faster to make decisions (as you can carry out impromptu meetings).
  5. According to Marissa Meyer, face-to-face meetings boost the quality of decisions and business ideas:

“Some of the best decisions and insights come from hallway and cafeteria discussions, meeting new people, and impromptu team meetings.”

Our opinion

Being a Technical Author is one of those roles where remote working can work well. However, it’s best to be able to have both options available – to have people who can come into the office within a short space of time, should there be an emergency. There’s a great deal of value in meeting people face-to-face, and to be part of a company culture (especially within startups), but it can help enormously if you can write in a distraction-free environment.

If you do work from home, you need to have a productive working environment, and be able to be self-disciplined.

What’s your opinion?

You can use the comment box below.

See also: Cherryleaf recruiting services

Writing user documentation collaboratively in an Agile environment


You provide wonderful newsletters full of useful information. Thank you.

I’m a Senior Technical Writer in a small company, and I have one contractor working for me. We have come up against a challenge. <snip>… My team currently uses RoboHelp, which is not a collaborative, team tool for writing. The company likes to think the product addresses this issue, but they really do not.

I have searched for a writer-friendly product that allows collaborative, team writing on a project. Unfortunately, I haven’t found anything. What product do you recommend for teams working on projects together? Right now we have to share files, meaning only one of us can work on the project at any given time. This is a serious issue for us since we are in an Agile development environment where we support twelve developers. More will be added soon, but we there are no plans to bring on more writers.


How would you advise TS?

Turning employees’ knowledge into an asset for the organisation

In July 2010, Mark Prisk, UK Minister of State for Business and Enterprise said:

As the events of the past two years have made painfully clear, we must leave behind the over reliance on financial services and support a renewal in modern manufacturing, so we are able to grasp the huge opportunities of the low carbon age. The ideas, skills and innovations of manufacturers will be just as important to our economic future, as the mills and mines were in our past.

Ten years ago, you’d find many consultants raising the issue that an organisation’s ‘knowledge assets’ walk out the door every evening.

Today, that’s still pretty much the case.

Organisations found it was difficult to capture the knowledge locked in employees’ brains. Many invested in expensive systems that offered poor authoring environments and complex ontologies. Retrieving the recorded knowledge could be a dreadful user experience as well.

With the economic future of countries such as the UK being based partly on creating wealth from the ‘knowledge economy’ and Intellectual Property, and with the recent, exciting, developments in technology (such as the semantic web, screencasts, wikis and open source software) now is the ideal time to revisit the issue of how to capture, collaborate and disseminate knowledge within and without the organisation. For a business working in a difficult climate, it can be the equivalent of finding loose change down the back of the sofa.

Your online grammar reference guide

We’ve added a link on our Web site that will take you to the online grammar reference guide offered by Grammar to Go.

Built for business, Grammar to Go is your personal grammar specialist, ready to answer your questions wherever and whenever they arise.

It is very popular with professionals who spend their valuable time correcting errors in English before they can review reports and other documents.

How much time do you imagine is wasted on this? 

17 days to better grammar

You can sign up for a free piece of expert advice in writing skills every day for 17 days. It’s a great way to check your knowledge of correct English.

Managing a documentation project successfully – more jelly and ice cream

This video on simplifying business, using the metaphor of organising a children’s party, made me smile and consider how successful documentation projects are managed.

The presenter is suggesting managers need to, in complex systems, give up rigid control from above. Instead, they should watch for organisational patterns, encouraging the good and discouraging the bad.

The key to managing a documentation project is often more about negotiation than control. Many technical authors have found a simple but effective “attractor”: bring biscuits/cookies along to meetings with Subject Matter Experts. Rather than focusing purely a rigid project plan, perhaps more attention should be given to identifying the additional “attractors” you can create (more “jelly and ice cream”) and the “boundaries” you can establish. These may be more effective actions toward running a documentation project successfully.