Re: Reference Architecture document

Subject: Re: Reference Architecture document
From: "Peter Neilson" <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Wed, 29 Jun 2016 17:30:29 -0400

On Wed, 29 Jun 2016 16:56:03 -0400, Helen Mullally <helen -dot- mullally -at- alfresco -dot- com> wrote:

Iâve been asked to take on the creation and production of a Reference Architecture document, covering the hardware, software, and processes for a deployment. The document is intended primarily to support the sales process, rather than being a part of the product documentation.

Has anybody got any experience of writing or managing the production of a Reference Architecture document?

Do you have any advice on the typical SMEs to assist with the definition of the architecture and contributing to the content? Did you encounter any pitfalls or conflicts?

The major pitfall is to include a discussion of futures. If the "official documentation" claims that the product, or an expected enhancement to the product, is to have Feature X, then the failure or inability of the company to provide that feature may cause anything from lost sales to legal action.

How to handle the situation? That's usually beyond the writer's control, except that we might refuse to include lies. Back in the dark ages I saw a "computer" produced by a self-styled engineer in Brooklyn. He claimed it operated at one and a half times the speed of light, which he called "1.5L". I felt fortunate not to be writing his ads.

Another difficulty is that the specifications will slither around underneath you as you try to write. Eventually the slippage of the project (caused by bad engineering or bad design) will be blamed on the poor quality of the tech writing. Try to avoid that situation.

A third difficulty is that you will be called upon to do mind reading. Your inability to produce solid documents from vague hand-waving will be your downfall.
Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Reference Architecture document: From: Helen Mullally

Previous by Author: Re: suggestion box on intranet
Next by Author: Current industry trends for technical writers
Previous by Thread: Reference Architecture document
Next by Thread: RE: Reference Architecture document

What this post helpful? Share it with friends and colleagues:

Sponsored Ads