Industry Documents

How to write professional documents

I use some assignments to develop a style more suited for industry, for a working environment. In these assignments, I try to identify the minimum documentation types appropriate to small projects. In some of my modules, assignment 1 is greenfield so it is relatively easy. Assignment 2 is brownfield, you have already done the initial work in assignment 1 and you may have to consider downtime, rework, mitigation, etc.

Attention to detail is required, these are assignments at L9, and you cannot just “wing it”. The documents which you should submit are specified. You must submit with the naming strategies prescribed, in the format specified. They are usually specified to be in a ZIP compressed folder, titled with your “L” number. In a real project, if you answer a tender with a document wrong, you are unlikely to win the tender, attention to detail is required!

Sometimes students use commercial templates from real projects, this is generally a bad idea. The documentation required by a customer is specified by the customer, not by a provider, how ever big they are. Start any document by looking at what the customer wants, not what a large company wants to provide.

Wording should be that appropriate to that of a professional contracting to a major customer.

I give no extra marks for good presentation and grammar; it is expected at this level. However, I will deduct marks for poor presentation.

Good practice is to have a minimal number of fonts and text colors in use per page.

The layout should be clear, and I should be able to understand any document rapidly. Your word processor should underline typos for you and if you are not a mother-tongue English speaker, you might use a specific tool like Grammarly.

It can be very hard to get the style just right, when I write, I sometimes look back on documents and realize I have failed to meet my own rules!

With these industry documents, the style of writing is different from an academic document and can be hard to get just right. When you read industry “glossies” they are full of nonsense, we used to jokingly call this "consultanteze".

“This contemporary holistic technology leverages machine learning and provides a market leading value proposition for verticals”.

Avoid this type of verbiage/garbage. One of your checks when you proofread before submitting is, if I remove a sentence, does it take anything from the document? And adjectives...don't get me started on adjectives! In almost all cases, they have no place in an engineering document.

When you are using numbers in a sentence, spell them. When you are working with actual numbers, you may just use the numbers. For example: “There were twelve firewalls, all at firmware version 2.6”. Some judgement is required, and my notes may not always conform to this.

The first time you use an acronym, fully define it. Depending on the document, you may need to create a list of abbreviations and acronyms, there should never be a case where ambiguity can exist. If I need you to concentrate on KVM, do I mean on the Kernel Virtualization Module (KVM) in Linux, or the Keyboard, Video, Mouse (KVM) system in a data centre rack?

We are writing technical, not literature. I should be able to glance at a document and understand it. It should be structured, clear and concise, no waffle! One of my starting points for writing is to put in the headings for what has been specified. The first section will always introduce the document or define the remit. Then put in points for each section as to what each paragraph will be about, based on the course notes and research and based on discussions in the chat forum for the module. With that structure in place, writing is easy, elucidate on each point.

On large projects, project management and documentation will be formal and complex. Quite frequently, it will be standardized and based on the discipline of the work being completed. The documentation library itself and its revision history might be dictated by something like ISO 9000. Understanding this area is a full subject, and I will not be covering it!

Project management itself is a discipline which requires formal learning, but to be effective, it really requires mentoring and experience. It has a language all its own, and most of us use tools like Microsoft Project for basic logistics and planning. On large projects where there are shared resources, a tool like Microsoft Project is the front end to the underlying resource databases. An example of such a system is Microsoft Project Server, briefly review its application, and its functionality.

If you want to pursue project management as part of your career, look at traditional certifications like the Project Management Body of Knowledge (PMBOK) and PRINCE2. In a more modern environment, you would also need to look at Agile, Scrum, Kanban, Lean and Six Sigma, at the very least.

As part of the software available to you through the University, you do have access to Microsoft Project. If you are interested in projects, I recommend you download and install when you finish the taught modules. Find a basic online course which covers an introduction and the terminology. You will find this of use if you ever do this work in industry, but we will not be covering it in this module.

For smaller projects, the approach may be informal. In this section, I describe some typical documents I might use in a real project for a small or medium enterprise (SME). I have been doing projects of this nature since the 1980s, on four continents. Consider what we do here to be a minimum!

In writing for business or industry, write formally, but you are not restricted to the same style as academic writing.

Normally, you do not use references.

When describing physical properties, only use SI units. In a real world project based in the US or UK, there may be exceptions to this. For all work on my modules, use SI units only.