Documentation that serves your purpose is a piece of engineering, not a work of art.
Availability: December 2022
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.
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 have three companies: two doing digital printing, one doing documentation engineering.
MIE Print is our commercial digital printing and print broking operation. The Book Printing Company specialises in short (1 copy) to medium (5,000 copies) print runs of books in full-colour for self-publishers and small publishers.
I am the principal of McGhie Information Engineering Pty Ltd, a privately-held Australian company specialising 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
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 companies.
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.