Documentation that serves your needs is a piece of engineering, not a work of art.
Availability: Available November 17, 2014. Click Resume to download my current resume.
Unit 38, 24-28 First Ave,
Sydney, Australia 2148
By Email: mailto:firstname.lastname@example.org
By Phone: +61 (0)4 1209 1410
Welcome to my personal web page. As you can tell, this is simply the page upon which I park my resume. My real website activity takes place elsewhere: I am the webmaster for http://www.word.mvps.org
However, if you look at as many web pages in a day as I do, perhaps you will appreciate a webpage that is very simple and so loads extremely quickly?
I am the principal of McGhie Information Engineering Pty Ltd, a privately-held Australian company specializing in documentation engineering.
Documentation engineering begins with the premise that "Documentation that serves your needs is a piece of engineering, not a work of art" – which just happens to be my company slogan. That's what we really do: We analyse what you want people to be able to do after reading your documentation and we analyse what they already know. Then we design a suite of information resources to bridge the gap.
Documentation engineering is normally practiced by a team of five or
six people, including the documentation engineer, one or more subject matter
experts, a business analyst, a project manager, an editor and a production
editor. Projects may run one or two years and of course the budget can be
substantial. Projects such as this are best suited to "clean-sheet" design
tasks, where the customer needs to establish an entire library of documentation
for a new product or company. The key to documentation that remains successful, standards-compliant
and economical throughout the entire product lifecycle
is the strategic planning that occurs before the first word is written.
My company also offers Technical Writing services. The difference between
Documentation Engineering and Technical Writing is mainly one of scale.
A Technical Writing project may have only one or two people on a job. Technical writing is the process of collecting and structuring information, and rendering it in multiple output formats for dissemination: including paper, web sites, help files and XML knowledge bases. Technical writing is still engineering, but typically creates or updates the literature for only one product.
Some of our clients are already resourced for a combination of Research,
Analysis, Design, Review, Editing, or Project Management functions. We can
supply one or more people to fill in the gaps. Some of our people are experienced
working Fly-in, Fly-out on resources projects.
Microsoft says that Word is easy to use and extremely powerful. Both statements are true. Unfortunately, some people discover, a week out from their absolute deadline, that they are two separate statements. Large scale documentation is not "simple". The knowledge base of an average corporation is normally more complex than its computer system, and the management of it is a large scale undertaking. It's really a bit like flying an A380: easy; if you know how. If you don't happen to have an Air Transport Pilot's License in your back pocket, we'll send you someone who has.
The term macro is much-abused in the industry these days. It was really coined to describe a small re-useable routine that an end-user could create in a few seconds to automate a repetitive task. The power and programmability of Microsoft Word has closely observed Moore's Law: a Microsoft Word "macro" these days is sometimes several thousand lines of object-oriented structured programming that offers very substantial return on investment. Or it's a business liability that keeps your contingency planner awake at night. If you would like one of the former kind, give us a call!
We now offer commercial Microsoft Excel VBA coding. Our focus is more
on data management and manipulation than mathematics.
The key to successfully deploying any automated system is to "make the
right way to do the job the easiest way to do it". We believe it is unrealistic
to expect busy senior people on a project to learn fiddly procedures for
doing things. They simply won't do it, and the project rapidly ends up in
a mess! So we create our "management system" as one of the first things we
do on a project. And often, we create it in Excel, because it is available
and it's powerful enough to do most things we need.
Effectively, we are simply offering one of the "tools we use in our business"
for independent purchase. Documentation Engineering projects tend to be "large". We
can all manage five pieces of information on a whiteboard, and if that's
all we have to manage, a whiteboard is the best way to do it. A Documentation
Engineering project can easily grow to multiple project leaders, perhaps 50
contributors, hundreds of documents and thousands of different pieces of
information. We can easily be tracking more than a million artefacts.
At some point we need some machinery to keep track of what is going on. Obviously Microsoft Project and Microsoft Access are designed for this purpose, and we use them when they are available. If they are not, we do it in Excel, and we can do that for you.
We will also tell you if you are attempting a job that is really too
much for Excel. We are aware of some consultants who will just sit there happily
munching your budget if you ask for a job that is beyond the practical capabilities
of their technology. We would rather give you that information up front, so the decision on whether
to continue, or look for a better solution, remains in your hands. And we
won't accept a job unless we're confident that we can do it well: if your
requirements exceed our capabilities we're happy to refer you on to partner
Business analysis is a key component of documentation engineering. It is the formal process of analysing needs and specifying requirements. There is abundant evidence that the really expensive mistakes happen through inadequate business analysis. "Any fool can make a mistake; a real disaster requires an entire project team (and a database)." The three immutable truths of business analysis: users know what they want, but not what they need, businesses know what they need, but not what they want, and developers don't understand either. It is difficult to prove that successes come from good business analysis, but you may wish to bear in mind that "If we are not planning to succeed, we have already planned to fail."
Writing the responses to requests for proposals is a specialised area of documentation engineering. Producing a substantial response tends to quickly sort the players from the stayers in our industry. Most technical writers can successfully produce a 2,500-page document, given sufficient time and resources and a relaxed quality requirement. People who can successfully manage a 2,500-page RFP project with six weeks to deliver, and survive the rigours of a government bid assessment panel, are much less common. There are very few who can do it well enough to win $500,000,000 worth of business! We can. We have. Yes, I know: luck and politics are important attributes in such a project, but customers who may well be betting the financial survival of their company on the outcome tend to be very risk-averse! Large-scale documentation required in very short timeframes really finds out whether the project team knows what it is doing with its project management, requirements specification, traceability and production engineering. Delivery day is not a good time to discover that your production database is corrupted!
Contingency planning, often termed business continuity planning, is a
branch of business analysis. A wise man once said "The first secret of business
is to stay in business." Business continuity planning is the discipline
of working out (ahead of time!) how you will conduct business after things
go wrong. The Sarbanes-Oxley act now brings the very real prospect of unpleasant
personal consequences for the directors of companies who display inadequate
diligence in their corporate governance. One of the things shareholders
expect boards to be diligent about is business continuity planning. There's
evidence to suggest that a major company these days is unlikely to survive
financially if its core computer system is down for longer than three days.
"We're all right," I hear you say "We have a backup system and a diesel
generator -- what could go wrong to take the computer down for three days?"
A broken water main.
I'm kidding you, right?
No. I'm not. No water means no cooling towers. No cooling towers means no air conditioners. No air conditioners means no computers. No computers means no business. And the Sarbanes-Oxley Act means the CEO gets to sit in a jail cell ... While turning over in your mind the new and interesting friends you would spend your evenings with in a jail cell, maybe you would like to give your building engineer a call on Monday and ask just how long your building could operate without water.