1

Process Manual

Title: Documentation Process Guide

Author: Lundrim Lluga

Version: 1.0

Presented to: INSPERA

 2

“Writing is a sweet, wonderful reward” - Franz Kafka

 3

PURPOSE

This procedural document is written for many different audiences whose

activities are within the field of technology development, more specifically

software engineering and the likes. However, primarily this document aims

to serve technical writers and guide them towards the process of

conceptualising, facilitating and properly developing technical

documentation. As a result of these processes that are described within

these documents, other technical writers must be able to easily create

documentation that is vital, which directly contributes to the software

development environment. Furthermore the document will contain very

detailed information, concepts, processes and practices that equip the

intended technical communicator to produce documentation that correctly

resonates with the audience and effectively conveys complex information

with clarity and precision. By taking this group of factors into consideration

we equip the reader as well as technical writer with the sole purpose of this

documentation, which is to provide guidance, understanding and a

continuous effort on education the technical community at large on the

crucial importance of technical writing. That being said, the document does

acknowledge the broad range of writing activities that fall within the scope

of technical writing as a concept, however this document aims to provide

guidance that is specifically targeted towards software oriented

documentation and technical materials as a whole respectively. By following

 4

the prescribed disciplines that are explained within this document,

technical writers can become more confident in their writing and correct

delivery of intended information to their designated audiences. They will be

able to ensure that the documentation that they have produced will

empower different users of technology products, and furthermore will also

allow users from different walks and backgrounds to also be able to

effectively follow technical processes that can result from technical

documentation, most of which, in nature, is primarily internal by nature.

Suffice to say that the document does treat all of these concepts in great

detail and does provide sufficient information that allows the writer to

prepare instructions that help people in the technology sphere make the

right decisions in relation to the product that they are interacting with,

which is after all what technical writing is all about. It is about helping us

make the right decisions when working the systems and software. Another

very important facet of technical writing is the ethical use of technology;

therefore this document is a core source of advocacy to promote ethical

engagement with technology.

The entirety of the work processes that are described in the course of this

document are suitable for the preparation of materials and documentation

for all sorts of technologies.

The document will talk about the importance of well-prepared

documentation as well as its large contribution to effective communication

especially that of which takes place in software development environments

 5

which as a result produces effective knowledge transference and

information governance, two of which are pivotal factors in technical

writing. As a technical writer I firmly believe that it is very important that

we take the time to work on as well as think about the necessity of

providing a sufficient overview on these technological processes that must

be followed by companies and organizations. Although, it is very true that

the main responsibility for such activities to take place falls on the

shoulders of the technical writer, who must do his/her best to be able to

effectively convey the vision for a well-documented software environment.

When we talk about the significance of technical writing, we must always

take into grand consideration the writing standards for consistency and

accuracy of information. It is of paramount importance that we follow these

rules when preparing any sort of technical documentation, because we take

on the responsibility of translating the complexity into a language that can

very easily be understood by all, that on itself is more than enough to work

on, what follows next is merely a contributing factor of this established and

fundamental rule, without which you will not be able to write.

Therefore by providing sufficient written materials for different profiles

within the industry, we as writers ensure that the information that is being

streamlined is very simple and very easily understood. We create

comprehensive and coherent technical documentation that leaves no room

for interpretation. Uniformity of information is a key factor that should

always follow the writer, in other words it is your moral and professional
 6

duty to make sure that everyone understands and reads the same

information. It is also very important that the technical writer is

continuously engaged with their work, this means that it is crucial that you

are a voracious reader where you have a strong appetite for words, you are

very adaptive towards learning and being exposed to different technologies

and forms of documentation, and that you are most importantly confident on

your work by knowing your direct contribution to the ecosystem that you

are working in.

Consequently, this document is prepared first and foremost from a

philosophical standpoint of understanding. Technology has many ways of

being understood, because as a medium it is home to different users that

use it for different reasons and gains, be those personal in nature or

professional that is entirely dependent on the specific user. So, by

presenting technology primarily as a philosophical medium, we can better

explore different kinds of implications that can fall under that realm of

understanding. Concepts such as information, writing, documents and

different kinds of considerations that we need to be aware of, should all be

mentioned to help us better understand the complexity of this medium for

which we intend to write about.

I want to preface by saying that this does not mean that I negate any other

approach to technology, be that of a societal or even engineering. What I

 7

want to emphasise is that fundamentally we must be capable of

understanding technology from a philosophical standpoint in order to

convey information more effectively and with ease of understanding.

Philosophy as a field has provided sufficient means of contributing as well

as important information in helping us better understand technology

without having to worry about the technicalities, but allowing us to envision

it and experience is first and foremost as a concept in our reality. Therefore

I have seen this line of understanding very reasonable to be incorporated in

this document as I strongly believe it would help magnify the understanding

of the reader in getting a better grasp on the interaction we have with

technology and how grand it really is.

Having established this main premise of the document, I want to go to

greater lengths and mention the different considerations that I have seen

necessary to include for the prospective writers to be aware of ethical

considerations, societal implications as well as your responsibilities as a

writer in relation to the written word.

It is very necessary to state that the entirety of the processes described

during the course of this document can fall subject to temporary change.

This change can come as a result of the nature of the project in which the

writer is engaged in, the purpose as well as scope of the documentation that

needs preparation, and other organisational needs that can result during
 8

the hiring period of the technical writer. Such changes are applicable to

both organisations as well as companies with which a contract for providing

writing services has been signed, therefore allowing the drafting process to

start.

Above all, I want to inspire writers to believe in their work, to bring out

their inner natural leaders, and to provide them with tools that allow them

to be analytical as well as confident towards absorbing new information

with a heightened degree of keen observation, and the desire to explain

things simply and with ease.

Last but not least, this document has been written with the hopes of

shedding a light of logical understanding on the complex relationship

between the man and the machine, all while providing crucial information

that equips us with the necessary tools to understand the machine.

The document will contain additional annexes that provide more

information in relation to the expected conduct of this document as well as

the rights of the writer in relation to the presented work.

 9

1. PREPARING THE DOCUMENTATION

Once there is a signed agreement between the contractual entity (e.g.

company or organization) and the technical writer, the act of preparing the

documentation can begin. As a process, I think that it is crucial to mention

that the preparation stage consists of a large number of activities that the

writer needs to take, which in turn secure the necessary information to

move forward with the document development process. These steps will be

described in detail during the course of this section including their

 10

importance to the writing process as a whole. It is important to mention

beforehand that the preparation stage of the documentation that needs to

be developed is pretty similar to every project, of course sufficient

consideration must be given to projects where the line of order of such

activities must be changed. This can happen when we are dealing with

technologies that require somewhat of a more modified approach towards

information gathering. However that is not something that occurs a lot of

times, therefore the writer can be confident on a standardised and

chronological line of information gathering activities that they need to

follow.

Now that we have pretty much defined some key elements and concepts

that help towards grasping a better understanding of the process of

preparation. It is safe to proceed further towards providing more

information that is needed, and that allows the reader to understand the

importance of understanding the subject matter thoroughly, it is after all

what they will be writing about.

What follows in relation to providing more information and help towards a

clearer understanding of the importance of the subject matter are mostly

rules that need to be followed when conducting the act of technical writing.

They are all crucial bits of information that help the writer, and it is

basically the process that starts everything. Without a plan and insufficient
 11

information in relation to understanding the subject matter that you are

writing about, the writer will be lost in the woods, and the documentation

will suffer.
 12

1.1 THE IMPORTANCE OF UNDERSTANDING THE SUBJECT

MATTER

It is crucial for a technical writer to possess in-depth information and

knowledge about the subject matter that they are documenting. Possessing

this level of information helps the writer towards creating a more refined

understanding of what they are writing about. When executed correctly,

such an understanding creates the necessary path upon which the writer

can produce accurate and insightful technical documentation. If this

knowledge is not present during the stage where the writer is learning

about the subject matter and absorbing the necessary information which in

turn would allow them to better develop the necessary documentation, it is

very easy for the writer to misinterpret or misrepresent crucial technical

information on the matter. The entire information that is presented to the

technical writer during this stage is crucial in nature, and will later on play

a vital role in the documentation process, therefore if it is not treated on a

regulated and serious manner by the writer in this case, it can lead to

miscommunication and user confusion.

Another factor which is just as important when we are consulting our initial

understanding of the subject matter is without a doubt the act of taking into
 13

consideration the potential pitfalls that can happen. This means that these

pitfalls can arise when the technical writer lacks the comprehensive

knowledge about the technology, process or topic that they are

documenting. To go ahead and further elaborate on this point, I want to

take for instance cases when the writer is sure that they have grasped a

very deep and insightful understanding of the subject matter but in turn

they have already engaged in activities of producing documentation that is

riddled with inaccuracies.

If we are dealing with documentation that contains large quantities of

inaccuracies, misinformation, inconsistencies and ambiguities, this usually

translates into user difficulties to follow the presented instructions

correctly, which allows them to make the necessary decisions when

interaction with a piece of technology or trying to follow steps to

accomplish a technical process for that matter. This act can very easily also

lead towards a lot of troubleshooting activities with which the user has to

deal with. Troubleshooting directly disables the user from making informed

decision which primarily should have resulted from the documentation that

they have been consulting with. When accumulated together, the entirety of

these activities that can come as a result of not understanding the subject

matter in this instance, lead to unwanted user frustration as well as

potential errors on the system.

 14

Now I want to explore and provide a deeper illustration into how

understanding the subject matter in a way that makes sense to the user and

can therefore be considered as a complete understanding of the technology,

can also lead towards enhancing the clarity and the accuracy of the

technical documentation. Up until now we have very clearly stated that a

deep understanding of the subject matter enables the writer to explain deep

and complex technological concepts freely, clearly, with confidence and

concisely. Something else that does come as a contributing result of the act

of understanding the presented technical material is that the documentation

that is being developed becomes more accurate in understanding and way

more helpful to users of different levels of technical literacy in the long run,

which is an outcome that every technical writer, no matter the years of

experience in the field should always attempt to strive for. If they want their

documentation to help people that is.

I wish to continue with further clarifying factors that have not yet been

explored in this section of the document so far, and this I think would be

very well illustrated through examples where inadequate subject matter

understanding has lead to misleading or plainly ineffective documentation.

One of my very favourite examples that I always like to mention is when a

technical writer fails to understand the complexities and applications of

software features and functions. Almost always, in these instances the

technical writer may leave out crucial information that should have
 15

originally been a vital part of the user guide that is being developed. Such

an act results in incomplete instructions and as I mentioned earlier it

always results in user frustration. Another strong example is when the

technical writer is engaged in documenting medical software, or working on

different levels of medical documentation where mis-understandings of the

procedures and the system that is being documented can lead to

catastrophic consequences resulting in death.

There are many ways which I wish to explore in this section of the

document that relate to the direct contribution that the thorough

understanding of the subject matter has for the reader. This step greatly

affects the technical writer’s ability to correctly anticipate and address user

questions as well as challenges that may arise. As a process, the direct and

thorough understanding of the subject matter provides the technical writer

with many means of increasing the user experience. Firstly, through being

comfortable with what they are writing or documenting, the technical writer

can foresee the questions as well as potential challenges that the user will

encounter. This act grants the technical writer with a very stable degree of

integrity in the work which translates proactively addressing issues that

may arise. The activities that are usually a part of this process fall along the

lines of providing clarifications that the user needs for particular processes

and technologies that are being provided by the writer, even

troubleshooting tips which the technical writer sees as necessary to help

 16

the user make more informed decisions. Furthermore, the writer can create

FAQs that help with numerous questions that the users predominantly have

in relation to the technology that they are consulting. The preparation of

these knowledge based materials significantly enhances the user experience

which as a result reduces the support requests influx.

Another very important factor that I wish to touch up on is the confidence

that the technical writer needs to have in their writing. Surely, different

levels of confidence can come through years of experience that a technical

writer has in the field, however I want to preface by saying that a technical

writer’s confidence in their own writing instils trust among readers and

users of documentation. Confidence is amongst the strongest weapons on a

writer's arsenal, therefore it needs to be used wisely. To put it simply,

confidence comes always as a result of the technical writer’s passion for

their work, as well as a strong appetite to inform others, that is what makes

a technical writer confident in their work. This can be manifested through

the writer’s experience which instills interest and engagement in the

readers that consult the technical content or documentation. Through the

exercise of confidence in writing, the technical writer can demonstrate

authority and most importantly credibility of the technical information that

they are developing and presenting to the readers.

It is important that the readers perceive the technical writer as

knowledgeable, because through this factor they are most likely to create
 17

the human connection with the technical writer and therefore as a result

they can trust the information easily and use that to make informed

technical decisions. Clarity in the presented information almost largely

stems from the technical writer’s confidence in what they want to tell the

reader. So it is very important for the technical writer to display trust in

their own work, this allows the readers to view the documentation as a

valuable source of information.

Apart from being confident in your writing, there are some very important

and useful strategies that technical writers can employ, which grants them

a firm understanding of the complex technological subjects before starting

the documentation drafting process. Note that these strategies can vary

from individual to individual because everyone has their own way of

conducting these strategies which are largely based on what they wish the

end goal of the documentation to be like, usually as a procedure it is largely

defined by the nature of the project or technology that awaits

documentation or by the scope of the documentation and the use for it,

surely there are other factors but by definition these are the two largest

ones that affect the process. I tend to follow a set of strategies that allows

me to create successful and informative documentation. My process in

relation to these strategies mainly consists of; communicating and

interviewing subject matter experts, conducting the necessary technical

research on the technology or process that I am expected to write about,

 18

attending relevant trainings or courses that help me grow as a technical

writer and stay abreast with the latest developments on the field and last

but not least get rid of my TV and keep on reading and writing.

As a technical writer I think it is very important that we also touch briefly

on the connection between subject matter experts and the technical writer’s

ability to adapt the documentation that is being prepared to different

audiences and proactively be able to cater to their needs and expectations

in relation to the technical documentation. I firmly believe that the

relationship between the subject matter experts and the technical writer is

one of the most important factors in the process of correctly developing

technical documentation that solves problems. They continuously empower

technical writers to do their job and do it well. One of the greatest means by

which subject matter experts do this, is that they elaborate or even simplify

on the content based on the audience needs, knowledge level and so on.

Direct communication as well as interviews that the technical writer

conducts with the subject matter experts help greatly in ensuring that both

beginners as well as experts find the presented documentation or technical

content valuable, comprehensible and most importantly actionable.

There are of course many great instances where the technical writer

correctly understands the subject matter and therefore produces

documentation that does meet the standards of information display and

 19

governance. A correct and deep understanding of the subject matter always

positively impacts the creation of documentation, no matter how

complicated the technology is.

When the technical writer has garnered a deep understanding of the subject

matter which always comes as a result of prior consultation with the

entirety of available internal technical documentation, the preparation of

technical documentation will always be easy. Developing user-friendly

software manuals that thoroughly understand the subject matter leads to

user satisfaction, which is what documentation is all about.

It is very important to note that a deep and clear understanding of the

subject matter always comes as a result of a group of several factors such

as; passion for what you do, persistence, confidence, ongoing learning

attitude as well as practicability. Technical writers are always required to

stay up-to-date with advancement in the subject matter that they are

working with. It is essential to maintain a healthy appetite to continue

reading, growing and learning, because this essentially directly contributes

to the relevancy and accuracy of your technical documentation. Such a fact

ensures that the documentation that has been produces aligns with the

latest features of the system, different technologies that are being used to

facilitate those processes that need documentation, as well as ultimately

being of benefit to both the users and the organisation.

 20

1.2 RESEARCH AND INTERVIEWS

The research and interview stage in the documentation preparation process

consists of many activities that take place, most of which are heavily reliant

on direct communication, which as a process should be established very

early on by the technical writer in relation to the company. It is important to

mention that suitable communication means along with frequencies of

communication must be defined, however we will talk more about the

importance of direct communication as this document progresses. Now we

should focus on the act of doing the necessary research that allows the

technical writer to obtain a clear and deep understanding of the practices

and technologies that need documenting. This is directly followed by a

special set of interviews that need to be conducted by the technical writer

in cooperation with the subject matter experts. This section of the document

explores the means of discussion that need to be established, that allows

the technical writer to consult relevant material that relates to the system.
 21

When commencing the research preparation process the technical writer is

advised to be cautious of a few steps that follow and that need to be a

crucial part of the correct execution of the process. It is important that the

writer upon initially consulting the system, creates the key objective goals

of the research before engaging with SMEs. By doing this, the technical

writer makes sure to have some initial defining information that guide the

streamline of information that will be obtained from the SMEs through

means of interviewing. By being properly equipped with this information,

you already have a pretty solid map on which you are expected to build

upon together.

Having a set of information already ready, not only provides the technical

writer with an initial understanding of the system, but it also allows them to

conduct means of choosing the right SMEs to conduct the interviews with

so that they obtain the right and profound technical information. This

document will explore the relationship between the technical writer and the

SMEs in great detail while providing standardised steps on how to go about

your way when requesting the necessary information that you need to write

about. The identification and selection of the right SMEs provides a pivotal

point in the writing process and it can greatly affect the documentation as a

whole, therefore it is important that a set of rules is followed in order to

successfully accomplish that. Furthermore to complement this very

important relationship, I will also provide information on the kind of

 22

background information that the technical writer needs to be equipped with

before approaching SMEs, such documentation is very crucial and it saves

both the technical writer and the SMEs sufficient amount of time therefore

it leads to more efficient writing and task completion on both ends. The

background information and existing documentation can vary from project

to project or depending on the technology that is being documented,

however the means of conducting said information usually remain the

same.

However, before we explore the crucial relationship between the technical

writer and the SMEs, we need to take a closer look at what the research

objectives and expected outcomes of the documentation project will be. The

following section deals with exactly this type of information.

1.2.1 RESEARCH OBJECTIVES AND GOALS

 23

Earlier in this document we talked a little bit about the concept of subject

matter as well as the means by which the technical writer is expected to

gain a thorough understanding of it. This was followed with some very real

examples of what can happen when the technical writer fails to understand

the subject matter correctly in order to be able to write about it effectively,

in a way that creates bridges of understanding between the user and the

technical writer. We also looked at some examples on the types of fatalities

that can happen as a result of incorrect and insufficient technical

documentation.

To set the tone for the remainder of this document, it is necessary to clearly

state that understanding the subject matter correctly, should be the primary

goal of the technical writer. As we mentioned before this involves activities

of acquiring knowledge about its intricacies, functionalities as well as any

other related concepts of said technology or process. We must not forget to

consult all available internal documentation as well during this stage, the

more information you can gather, the less headaches you will have later on,

use it well.

What we will continue exploring on this section of the document revolves

around the key objectives and expected outcomes from your project. After

grasping a firm understanding of the subject matter, this provides the

technical writer with sufficient means of information to proceed towards

 24

identifying knowledge gaps that are found in your documentation so far,

which is where the technical writer can pinpoint areas where SME

intervention to fulfil these informational gaps is necessary. Such

information already gives you some pretty solid outlines that allow you to

correctly approach SMEs and ask for their guidance in further

understanding the technology that you are writing about.

Something else that the technical writer should always be very aware of is

the process of clearly defining the documentation scope. Now, we can

gather from experience that, as I have stated before on this document, the

scope of the documentation can change based on the project or technology

we are working with, However, it is very vital for the overall consistency of

the documentation that the technical writer in this case, conducts

reasonable and standardised means of clarifying the documentation scope.

This would mean that there needs to be a strong sense of definition in

relation to the document, followed by the understood scope of the document

while also taking into strong consideration the limitations that it can have.

Through these steps, the technical writer can obtain a better understanding

of which parts of the subject matter need to be included for further

consideration by subject matter experts, and which parts can be left out of

the contributing documents that await approval.

 25

Special attention in the research process must be given to audience

analysis. The technical writer in cooperation with the company needs to

conduct direct means of analysing the audience for which we are writing.

The steps that need to be conducted by the technical writer should focus on

assessing the audience’s needs based on their background knowledge,

technical literacy level, their needs as well as their expectations in relation

to the documentation. These are not steps that need to be adhered to only

for external audiences, similar steps need to be taken into account when we

are writing internal documentation as well. When we approach audience

analysis, it is very important that we start with our internal audience in

mind, usually the answers that we are looking for are right there in front of

us, a good technical writer always consults his existing resources first.

Having a complete analysis of your audience allows you to obtain an

entirely new level of understanding towards the technology or process that

you are documenting. It helps you tailor your documentation to the level of

their understanding, and therefore makes you a more effective technical

writer.

After effective audience analysis the research process can proceed towards

a more refined sense of information structuring that usually manifests itself

in content structuring. When we start content structuring it is important to

keep in mind key activities that help us effectively plan the overall structure

and organisation of the documentation. Therefore, the technical writer

 26

needs to be able to decide on how to present the entirety of the information

in a way that is logical and accessible for the readers. Having a logical

composition of your draft documentation makes it easier for it to be

internally understood, in this case by appointed SMEs that need to be

contacted for additional information where as a result interviews need to be

held.

A very useful asset on this part in the process is the act of formulating

questions that need to be forwarded to the SMEs. By means of effective and

clear question formulation the technical writer develops a valuable set of

insightful questions that are specifically targeted towards the SMEs, which

in turn allows them to provide information constructively. The primal aim of

these questions should be to extract specific information that the technical

writer requires for their documentation.

Usually after receiving a substantial amount of information from the SMEs

initially, the technical writer should be able to extract the documentation

objectives, whether the presented documentation is external or internal the

procedure of correctly defining document objectives is not largely subject to

change, however modifications to this procedure are individual to the

technical writer. The process usually involves considerations whether the

document is entirely informational, instructive and trouble-shooting

oriented. I say this mainly because for a documentation to be considered

 27

valuable as well as result in great usage by the user, it is important that it

presents itself as multifaceted and addresses the problem in different levels

of understanding, not just plainly displaying the information. Therefore,

there can be other combinations of factors that can take part in this

process.

During research and information gathering, the technical writer should be

aware that the information that they are working and gathering on, as well

as structuring so far needs to be in par with specific industry or

organisational standards of documentation conduct. In order to successfully

integrate those necessary standards in our documentation we must first

identify them and analyse on how they enrich the initial display of our

documentation, and then ensure that the research that is being conducted

as a means of primal information gathering is in compliance with these

standards. It should be noted that standards can vary depending on the

industry, however because this document is prepared to address processes

that are necessary to conduct effective software-oriented technical writing,

such standards should be followed accordingly.

It is the responsibility of the technical writer to focus entirely on conducting

effective research prior to starting the interviewing process and therefore

effectively approaching different SMEs. Another layer of effective research

is the ability of the technical writer to ensure that documentation meets

accuracy and completeness quotas. That being said, at this stage in the
 28

research, the technical writer should be able to verify and validate the

information presented through the information that they have gathered so

far. A result of correctly meeting accuracy and completeness quotas on your

documentation should give the technical writer means of identifying gaps in

the existing documentation and areas where updates or revisions are

necessary. If your research has been structured so far, you should be able

to guide these improvements that can take place in your documentation.

Before approaching the SMEs, it is crucial that together, the technical

writer as well as the appointed SMEs to be interviewed correctly assess the

preferred means of digital communication. It is preferred that email is

considered the official form of communication, this mainly because of it’s

usability in organisational environment, but also because of the suitable

information display and correspondence. And also because of the fact that it

allows the participation of different personnel or managerial and executive

staff in the communication as well, which provides clarity and transparency

of information transference between parties. When speaking about

collaboration framework, something that needs to be clearly defined in

writing is the frequency of communication as I have briefly mentioned

earlier, and last but not least there should be a communication of mutual

expectations that both parties have from the successful completion of the

project. There will be more information in regards to the communication

 29

between the technical writer and the SMEs in the coming section of this

document.

A dedicated technical writer is in constant control of his work, therefore the

most effective way to continue improving your work in a technological

environment is through the employment of quality assurance operations.

The technical writer should establish a structured plan that allows them to

plan out reviewing their work and addressing internal comments that may

come from different levels of personnel. This step allows the technical

writer to assess and validate the information that has been obtained by the

SME once the interviewing process has started. Apart from that, conducting

these activities towards the written work, allows the technical writer to be

ensured that the collected data is entirely reliable and in alignment with the

project’s objectives.

Once the aforementioned processes have been solidified and allocated in

your strategy, the following factors that should take place is establishing a

process of creating your documentation timeline. By drafting a

documentation timeline you can include various contributing factors that

will later on prove very useful in managing expectations and deadlines. This

document can include, but is not limited to; milestones of research,

drafting, reviews and finalisation of the document which concludes the

process of writing.
 30

The research process involves a great deal of resource allocation activities

that need to be established beforehand. Often, the act of correctly

determining the resources that are required for your research involves

direct communication with other company personnel as well, where the idea

is presented in a written form and then the adjustment in regards to the

allocation of said research can be done accordingly. For example, the

technical writer might ask for access to complete or partial previous

internal documentation that would help them obtain a deeper

understanding of said process or technology, other times the writer will

most likely need access to specific authoring tools, software or additional

experts. It is advised that the need for these resources is communicated and

identified early on so that necessary preparations can be made by appointed

personnel.

The last part in the research process has to do with ethical considerations,

which should be taken into great consideration by the technical writer.

There are a number of ethical considerations that need to be taken into

consideration that can be related to the subject matter of the project,

privacy, security, or data sensitivity and transference. It is of paramount

importance that the documentation aligns with ethical standards.

1.2.2 SELECTING THE RIGHT SUBJECT MATTER EXPERT

 31

The act of selecting the right subject matter expert to provide their

expertise in helping the technical writer develop the technical

documentation is crucial to ensure accuracy, effectiveness and

comprehensiveness of the work. This section explores the entirety of the

steps that form the relationship between the technical writer and the

subject matter expert, which as a result provides them with the correct

means to finish their work successfully.

We will go through a deeper exploration of different concepts, ideas and

processes that aim to solidify the professional relationship between the

technical writer and the subject matter expert as a whole.

The selection process begins with defining the documentation needs where

the subject matter can intervene and help with their technical

understanding of the system or process, and provide the information in a

structured way. It is the responsibility of the technical writer to clearly and

succinctly define the scope and the objectives that are presented to the

subject matter expert. This presentation of information should include a

clear list of prompts that indicate the kind of information the technical

writer needs from the SMEs as well as mentions of expertise.

 32

Sometimes, depending on the technology or process that is being

documented, there are instances that require an assessment whether you

will contact an internal or external SME. In cooperation with other project

executives, the technical writer can make the correct decisions whether

they should contact internal or external staff. Depending on the scope of the

project this decision can vary from company to company.

Furthermore, an important step in the selection process would definitely be

the act of leveraging internal resources that are related to the project that

the technical writer is involved in. It is important to make sure that there

are internal resources available that can be contacted and that possess the

required knowledge. Usually, these individuals are accessible and can

provide the required insights in the subject matter that demands writing. If

internal resources are not available, the next logical step would be to

establish prior connections with external experts that can provide the

necessary information.

Sometimes while the technical writer is on the selection process and

therefore is planning on reaching out to a potential SME, they forget to

consult existing documentation on said practices or technologies that might

be available internally already. Oftentimes, this documentation does contain

valid points and prompts that can be reused by the technical writer, and

that help them prepare the necessary questions that they need to present to

the SME. Furthermore, this can help the technical writer identify personnel
 33

who is familiar with the topic, and who has contributed to similar projects in

the past, therefore it assures the technical writer that they do possess the

relevant expertise.

When information gathering, a technical writer consults all of the tools that

are at their disposal, this is extremely crucial when preparing a display of

questions for the SME. It is very professional that the technical writer

approaches the SMEs by being prepared, knowledgeable of the information

they wish to obtain as well as maintaining an attitude of open

communication. There are many great means that allow the technical writer

to continuously leverage their written communication through ongoing

engagement in different technical forums or online communities where they

can get crucial information from industry experts online.

A very prominent stage in the selection process is the act of assessing the

expertise and the availability of the SMEs that need to be contacted. This

process is carried out in cooperation with the entirety of the managerial

staff, so that the technical writer has more information on who should be

the person that will provide the necessary information in regards to the

project. Together with project personnel, the technical writer must conduct

steps that assess the expertise and availability to participate in the project.

There needs to be sufficient information that outlines the experience and

participation in similar projects in the past.

 34

After the necessary assessments have taken place, what follows next is the

commencement of the interview process to test their communication skills

and as well as their compatibility with your project’s requirements. While in

this stage of the selection process, it is very vital that the technical writer

clearly communicates their expectations, project goals, as well as timelines

to potential SMEs. The understanding of their role and responsibilities

within the scope of the project and their responsibilities in securing the

correct information in the documentation process is very important and will

serve a great deal later on in the interviewing process.

Ideally, what follows in the selection process, after the appropriate SME has

been identified and selected, is the formulation of a collaboration

agreement between the two entities. For the sake of maintaining a line of

effective, open and direct communication, it is advised that such a

document is prepared which would outline their involvement with the

project, as well as confidentiality agreements they must follow. Such a

process needs to be priorly defined with company officials.

The maintenance of open communication during the lifecycle of the project

is key. Both parties need to adhere to established and agreed rules of open

communication, so as to provide sufficient space that allows the correct

addressing of questions, updates that can result during the progress of the
 35

project and documentation process alike, as well as create the necessary

means to make it possible to seek out their input when necessary.

The technical writer needs to recognise and appreciate the contribution of

the subject matter expert in the project. Their help is vital in successfully

delivering any type of technical documentation, therefore a simple thank

you goes a long way in maintaining a healthy work relationship.

Once we have followed all of the steps that have been described in the

opening section of this procedural document, we can move forward in other

steps that allow us to take our documentation preparation process further

towards successful completion. There are many other factors that we have

yet to delve into and explain so as to ensure maximum retention from the

reader of this document.

 36

2. PLANNING AND STRUCTURE

The planning and structuring stage of the preparation of technical

documentation corresponds to a wide array of steps and procedures, all of

which I will describe during the course of this section. I will try my best as a

writer first and foremost to provide a logical and comprehensive correlation

between these concepts and ideas during this stage so as to inform the

technical writers that are consulting this document, on the importance of

following this set of rules that allows the correct activities of planning and

structuring to take place.

I believe that it is also important to provide a foundation of branching out

into these very crucial concepts and therefore allowing myself to provide

very intricate and important information wholly. It is after all very

important that the document contains a depiction of the entirety of the

process that should be followed when developing technical documentation.

The process starts where the technical writer is engaged in providing a

clear structure outlining of the document so far. This structure should be

based on the entirety of the activity that the technical writer has followed

up until this point, so naturally it is expected that this document outline

 37

contains vital information on the logical flow of the document, where it

depicts a logical strategy on how the users should be able to follow the

presented document it its entirety, all the while allowing the content to flow

seamlessly. Different kinds of technical documentation require different

approach to their structure, that much has always been known to those of

us who studied technical communication. However, when we take for

instance a software manual, naturally we would expect it to have a

determined structure that follows certain standards which aid on proper

content display, be that digital or printed, in any way, shape or form. So we

can go ahead and say that for a software manual, we already know what to

expect when we start reading it. Normally it would be divided into sections

that would help the user better navigate through the large quantities of

information that are described within. This goes to mean that the software

manual would be divided into “introduction” which would be the section

containing all of the primal information that the user needs to be aware of

before they start to use the software, followed naturally by the “installation”

section where we get a better and more concrete idea on how to operate in

regard to the software which would help us in providing the necessary steps

to install said software or system into our machine, and lastly we would get

a large quantity of organised information which would be titled

“troubleshooting” and as a result of that, the user would know what to

expect in terms of information display. This section would logically contain

all scenarios where the software would malfunction, followed by direct

 38

information and specific instructions that guide the user towards resolving

those presented issues, with adequate information on where to reach out if

the instructions do not prove useful and there just happens to be a user

case that has not been estimated by the technical writer. Which is

something that can result in happening sometimes, which is why contact

information should always be available so that the user can reach out to

dedicated personnel to have their technical issues with the software

resolved.

What really defines a document, no matter its scope and the subject matter

that it treats, is definitely the table of contents. It is such a simple device

that is applied when we start preparing the documentation, but it sets the

tone for the rest of the document. The primal purpose of the table of

contents is to provide a visual map for the user and prepare them for what

they can expect once they start reading the document. Ideally, the table of

instructions should be the focal point of the document which should

walkways be very easy to access, and in many instances, especially with

modern technical documentation it should follow the user throughout the

entire reading journey, this of course can only be achieved if the reading of

the document is in this case being carried out online. However there are

many instances where companies print out their user manuals, this is

especially true with hardware devices. The table of contents should be able

to grasp the reader in, and in a very natural way make them very interested
 39

in wanting to read the instructions that guide them on how to go about

using a piece of technology, or finish a process successfully. Whatever the

case may be, you can guide the reader through providing a well structured

and informative table of contents. Once you enable the readers to navigate

the document with ease, you have earned yourself an interested reader who

wants to read what you have written.

Next up on the process of structuring a technical document we want to

explore the importance of selecting the appropriate formatting for your

documentation. The best way to go about selecting the appropriate format

for your document would be to consult the information that you have

gathered during your audience analysis, that information should inform you

on your audience’s needs and expectations with the documentation that you

are preparing. So whether the documentation that you are developing is

internal procedural or technical documentation, or if it is user based

documentation such as manuals, guides, or even tutorials, you should very

easily be able to produce the necessary document format based solely on

that information. Something very important to keep in mind when choosing

the formatting of your document is that your choice of information display

will greatly affect the overall user experience. So it is crucial that you make

the correct assessment, consult the information that you have gathered and

then start writing appropriately to what is expected from the audience that

reads the documentation that you have written.

 40

Once the technical writer gets comfortable and confident on how the

technical document is being developed, this opens up the way for estimating

the desired goals of the document that you are working on, personally my

goal is always user satisfaction, now that concept on itself manifests itself in

reduced support tickets, because my document has answered some very

important questions that the users have posed. Moreover, good technical

documentation can also help facilitate user onboarding in many instances or

greatly improve troubleshooting. All of this is a result of ongoing efforts in

perfecting technical documentation.

Correctly selecting the documentation type as well as appropriate outline

for the document are two factors that do go hand in hand usually when we

are working on large or even small amounts of information. Both of these

factors complement each other in structuring the document so that it meets

logical prerequisites of information display.

Apart from the type of the document as well as an effective outline for the

document, the technical writer should also take into consideration the user

experience with the document at hand. A sufficient amount of research as

well as planning, by continuously gathering feedback from other members

of the team in regards to the user experience does make the document

more useful to the user. By thinking about how readers of the document are
 41

expected to interact with the document, the technical writer should adjust

the writing strategy in order to correctly meet information display

prerequisites, a deciding factor is the devices where the users are most

predominantly expected to read the document. Therefore text alignment

and correct display is mandatory.

Effectively planning towards incorporating multimedia elements into your

documentation increases the interactivity that the document will receive

from the readers be those internal or external users. So by placing images,

diagrams, charts and different tables, the technical writer makes sure that

those elements are specifically placed there to increase user understanding

of the presented information as well as make the document more lucrative

in nature. While relying solely on text can prove necessary and beneficial

for certain types of technical documentation, we should always strive to

make our documentation as modern and multimedial as possible, so that it

continues to serve its purpose.

Structural display of information greatly manifests itself in every facet of

the technical documentation that we are working on. A very good

application would be the incorporation of glossaries and terminology

sections in our document. Before application of said section, the technical

writer needs to correctly assess if such a step is necessary for the

document. Depending on the scope of the document, it is advised that terms

that are used within are properly defined so that users are not confused in
 42

regards to the information that they are accepting while consulting the

document at hand. As is the case in software development environments,

when the structuring of the document takes place, the clear and succinct

definition of technical terms that are used throughout the document needs

to always be properly defined, and this should be done according to specific

standards as well.

We can have a somewhat similar structuring step when the document needs

to have a section the defines document prerequisites that are usually listed

out and set forth by the technical writer. Such prerequisites mainly consist

of requirements that are considered as necessary for readers in order for

them to make the most out of the document. This sanction usually contains

very specific instructions that attempt to alleviate the user experience with

the presented document.

While we are dancing around the topic of user experience, it should also be

noted that when we refer to the user experience first as a primal concept

we must always take into account that it fluctuates and differs from

documentation into actual software. While writing technical documentation

what the technical writer can do to keep the reader or in this case the user

interested in reading the document through are a couple of very useful

steps that make the document even more easy to navigate. By using page

numbers we guide the user through the document and ensure them that
 43

they are following a linear display of information, furthermore when

inserting hyperlinks in our document we link information from the

document and lead the user into following the link that redirects them on an

external page or within the document, where more information can be

obtained for a particular topic. Usually when linking the article internally

the reader greatly appreciates it if they are not obligated to leave the

window where they are currently reading the document, this can be deemed

as an annoying experience for the user, therefore we must strive to present

the necessary information in one place where not much movement is

required. Bookmark incorporation also greatly helps with user navigation

through the document, however to obtain a clear view of the user

experience within the document, deep research is required. These are

merely some examples that help to illustrate the point, there are many

many more instances that make the document more desirable to be read.

Great technical documentation contains consistency. This goes to mean that

in order to correctly and effectively display information in a manner that

entices the reader to take the documentation at hand seriously and consider

it a valuable source of information, there are certain content structuring

factors that need to be taken into strong consideration. To ensure that the

documentation meets the needs and expectations of the reader, the

technical writer must ensure that the information that is being presented

follows standards of consistent formatting, font choices that are easy to

 44

follow, the appropriate use of headings, as well as lists when dealing with

large chunks of information that need to be divided into manageable chunks

of information so as to be easier to read and understand.

Audience analysis provides the technical writer with sufficient information

to also take into account different types of considerations that need to be

integrated into existing documentation so that it continues to meet the

needs of the audience. The technical writer must always write with

accessibility of documentation in mind, including considerations with users

with different disabilities and making the documentation useful for them in

the preferred devices of their choice. This process does involve a large scale

of the information so that it visually corresponds with the requirements of

the audience at hand. However, the goal of the technical writer is to reach a

wide range of readers, because the main premise is direct information

through effective and clear technical documentation.

During the planning process of our technical documentation development,

the peer review factor is considered to be of very high importance. Usually

the peer review process concerning the development process of technical

documentation with planning for the peer review in relation to your

documentation. The technical writer should make the entirety of the

documentation that they have been working on available to the

corresponding personnel within the company that is eligible to give

 45

constructive feedback in regards to the presented work. Oftentimes, the

entire team that is engaged in the process of peer review can provide

valuable feedback in relation to increasing the clarity and the outline of the

presented documentation. Therefore, peer review is a very organic process

in nature, however it does provide the technical writer as well as the entire

team with a unified sense of clarity towards the expectations that have been

mutually set in relation to the work that needs to be produced. The

importance of constructive and unbiased peer reviewing can help greatly

towards producing documentation that truly helps the reader and that

makes a lasting effect.

Another key factor that remains unchanged during this stage of the

development process is the crucial importance of developing an effective

revision strategy for your documentation. Moreover, when the technical

writer considers taking the necessary time to develop a revision strategy,

they do so to pave the way towards effectively and easily handling

document revisions that happen during the life cycle of the project. There

will undoubtedly be different versions of the same document as the project

goes on, which is why the technical writer in this case must develop a

cohesive revision strategy that involves version control for the document at

hand. Usually, this process starts with clearly stating and establishing some

standards in regards to the conduct of the document, such standards can

be; a clear outline on how changes that are made to the document will be
 46

tracked and incorporated to the established structure that is already in use,

clear steps on establishing authoritative editing, clear instances where the

technical writer indicates the level of access that should be given to certain

personnel and so on. These are just some very simple instances on how to

go about establishing your revision strategy, because it helps a great deal in

guarding the integrity of the information that is being transmitted as well as

following the versions of the document that are being produced. It can

become increasingly difficult to manage document versions as the project

gets bigger, therefore applying this strategy in unison with other company

personnel, and therefore taking the time to properly define the

prerequisites that it must follow, will save a great deal of valuable resources

in the long run.

Creating a timeline as well as setting completion milestones for the

documentation that is under development is yet another pivotal factor that

greatly comes into play and therefore can have the power to significantly

shift the development process entirely. It is very important that a timeline is

already in place which concerns the development, planning as well as

structuring phase. Such a timeline usually includes important milestones

that the technical writer deems important for the completion of the outline,

table of contents and the overall first draft of the document.

 47

We are very aware that every type of technical document that goes under

the process of development contains a set of metadata. Now the way that

we can view metadata is simply as data about data, they usually provide

more information about something that is already there. In our case, this

analogy still stands, so in terms of the documentation that we are

developing we could very easily classify such data as corresponding

elements of this document which are; version numbers, publication dates,

as well as authorship information which can all be found on the document’s

structure. Every well-structured technical documentation contains a vast

amount of metadata that is distributed on the document, which is why it is

very important to know the types of metadata that are being used. Including

metadata on your document makes it easier to stand out, be more useful to

the reader and convey the necessary information in a structured manner.

And therefore last but not least a very prominent step in the planning and

structuring process is the process of conducting user testing initiatives with

your document. User testing can be conducted very early on, if possible,

and it helps greatly on testing the structure of the document but also on

gathering useful user feedback in regards to the usability of the document

and its organisation of information. So as a whole, what the planning stage

can provide you with, when executed correctly, is that is sets the necessary

groundwork that enables the technical writer to create documents that are

informative, they answer the right questions and that are easy to parse
 48

through. As a result, by following the entire list of components and concepts

that are described in this section, the document is aligned with its intended

purpose. This information should help the technical writer navigate the

critical planning phases effectively and with confidence.

3. WRITING GUIDELINES

In this section of the document I will provide sufficient ground work that

attempts to aid the technical writer in finding a balance when using writing

to transmit ideas that they want through their work. Fundamentally, writing

is a very intricate and individual process that is largely based on the ideas

that are transmitted, the questions that are answered and the facts that are

provided. I intend that this section of the document will firstly serve as

means of conveying the importance of transmitting ideas through writing.

Evidently, the section will contain a substantial emphasis on technical

writing.

However, in order to transmit my view on the importance of writing, it is

needed that I base this set of ideas and concepts on finding a balance

between the humanistic and technical perspectives. One of the building

blocks of this entire document is truly the understanding of the importance

 49

that lies in conveying complex technical concepts in a clear and

understandable manner. In order to be able to transmit complex ideas in a

language that is easily understood by a wide audience the technical writer

must focus their entire style of writing in providing clarity through those

ideas as well as contain a strong establishment of understanding that the

presented work attempts to receive from the reader.

By continuously writing clearly we ensure that the audience that engages

with our work, regardless of their technical background will be able to

grasp the presented ideas and concepts with ease of understanding. A clear

and simple style of writing goes a long way when we want to foster

understanding amongst our readers and not confusion through the written

words. A technical writer must always write with the purpose of avoiding

misinterpretation that can potentially arise if our prose is deemed as wordy,

complex to dissect and contains a lot of unnecessary jargon that the

audience will not resonate with, therefore making the document not worthy

for further consideration by the reader. When the technical writer intends

to write with an ingrained sense of providing complete clarity as well as

fostering understanding through their work, their prose transforms itself

into being more persuasive for the reader to follow through, and actually

display deep interest to the document that they are reading. Therefore, by

providing the user with an honest and clear prose you maximize the

potential of promoting knowledge sharing, making your document very

 50

necessary to the user’s experience with the technology that you are writing

about.

Another facet of clear and simple prose is that it should contain within itself

a user-centred approach. What I simply mean by this is that good technical

writing provides the necessary means of offering consideration to the needs

as well as the perspectives of the users. By providing an environment that

puts the user at the centre of the documentation the technical writing

process becomes more valuable. A notably contributing factor in this

approach is the process of recognising that the writing in its entirety is

primarily meant to serve your audience, they are the ones that will make

the decisions that you have written about, and they will be guided by the

information that you have provided. So really, by truly emphasising with

your readers and taking the obtained information that has been gathered

during the audience analysis process, the technical writer should care for

their challenges, questions and most importantly their goals with your

documentation. By taking a humanistic approach in the writing process, the

technical writer will therefore be able to produce documentation that not

only meets the prerequisites that are set forth by the reader in relation to

the document but will also be received as very genuine and honest

information that helps them. So as a means of establishing a strong sense of

care towards your readers the technical writer will also be able to continue
 51

further into developing great documentation that focuses with a very strong

sense on problem solving.

Good documentation is measured by how it meets different factors that we

have discussed so far, furthermore in order for it to be considered truly

effective in solving real-life problems, the technical writer needs to make

sure that the presented work is directly solving the problems that the user

is facing. It should serve as a primary resource when considering resolving

troubleshoot issues or helping readers make informed decisions about a

piece of technology or process that they need to be able to follow. So by

using the presented means and guidelines to create documentation that

solves problems, the technical writer is able to guide the readers towards a

solution while empowering them with the knowledge that they need to be

able to make informed decisions. This process not only helps the readers

solve the problem efficiently but it also ensures that they consider your

work as a valid source of income that they always take into future

consideration when being presented with similar problems that require a

specific solution.

Good writing is always honest writing, having said that, we can entirely

acknowledge the role that the process of knowledge preservation has when

preparing technical documentation specifically. As a concept that is entirely

related to good writing, knowledge preservation presents itself with

 52

different sets of information that need to be heavily considered when

applying those into the written work. To make sure that the entire writing

process is carried out effectively and that it follows a set of guidelines that

aid towards maximising clarity and supporting knowledge governance, we

should analyse the role that our writing must take in order to meet those

specific needs that are deemed as mandatory. So, as the technical writer is

entirely engaged with continuously perfecting their prose so that it serves a

wide array of needs that can present themselves, be those internal

organisational needs or even needs that are presented for consideration by

the user, it should also be taken into account that the writing must serve as

a process of preserving institutional knowledge, which as a result prevents

knowledge loss.

By using the writing process in the aspect, where it entirely acts as a

repository for knowledge within the organisation, we ensure that different

crucial processes that are related to knowledge governance are already

being taken care of as a means of effective technical writing. We can take

for instance valuable insights, all of which are presented to the technical

writer in document form through the entire lifecycle of the project, which as

a result is an act that involves different personnel. In most cases when

developing documentation the technical writer will also engage with

practice documentation of different sorts, and procedures. So by mutually

establishing guidelines that allow the technical writer to create means that
 53

facilitate effective technical writing, the company will guard valuable

resources and ensure that documentation is being passed on to generation

without containing loss of information. Such an act is definitely a byproduct

of ongoing collaboration that takes place in different organisational levels

which should attempts to leverage a strong sense of consistency towards

the written work, primarily by the technical writer but also by other

personnel that is also heavily engages or has an ongoing contribution role in

the development of documentation.

Always by employing a strong adherence to writing guidelines, the technical

writer will be able to effortlessly promote the necessary practical guidelines

that are focused towards promoting consistency across teams and projects

that are active. The adherence and respect that should be played on these

very important guidelines ensures that the entirety of the staff are on the

same page in regards to crucial concepts such as; terminology, formatting,

and style.

Well-structured writing should also be efficient in strictly conveying the

desired message, this is a factor that should be present when developing

technical documentation in order to save time and other valuable resources

for both the technical writer and the reader alike. So when I use the term

well structure, I want to mean that the writing that is being produced

should contain a sense of clarity and organisation, which translates itself on

documentation that directly meets the needs, all while being easy to
 54

manage, which on itself proves another very solid fact that needs to be in

consideration during the development process. By developing

documentation that is easy to manage, the technical writer takes great

responsibility in delivering the necessary information in a manner that is

easy to search when needed, but that also enables the streamline of

different processes that are being documented. When applying all of these

crucial factors the presented material will increase the efficiency and the

productivity of everyone involved.

It is a very well known fact that when communicating ideas through

technical writing, the writer is very aware that there are several ethical

considerations that need to be taken into account. Through conducting the

considerations that need to take place in technical writing, the writer

ensures that the presented information contains a high level of honesty as

well as transparency. By taking these necessary steps towards the written

word we uphold the technical writer’s ethical responsibility to the reader.

By following the ideas that are previously mentioned, the technical writer

should be able to continue defining their writing style as the project

progresses. Defining the writing style is the key factor in the writing

process, however there are instances where new information may present

itself, be that information generated from the audience needs and

expectations with the project or other contributing factors. As I have

 55

previously mentioned, we must always strive to deliver information through

clear prose. But, sometimes depending on the audience for which we are

writing, we might have to make significant changes to the prose where we

adapt formal, informal, technical or even conversational styles of writing.

The kind of documentation that we are preparing is also a vital contributor

on this process, where for instance if we are writing a user guide that is

aimed at beginners, it would logically mean that the writing style would be

more conversational. As opposed to when we write detailed documentation

that is aimed towards developers, such as API documentation, where we are

heavily inclined to use entirely technical language because the audience

that we are writing for has no problems with understanding those

concepts.

Yet another factor that truly defines how the written work is received is the

consistent use of active voice when preparing instructions or even technical

documentation as a whole. Suffice to say that for the sake of correctly

carrying out the writing process, the active voice should be used

consistently because it is more suitable for clarity and readability. The

intention of the technical writer should always be to come across as very

direct in their writing, this fact is especially true when we are writing very

complicated and important instructions that address certain procedures or

technologies that need to be accessed through those means. The only

instance where the use of the passive voice would be more suitable in
 56

writing than the active voice would be when the technical writer wants to

shift away the focus from the object. But in pretty much all other instances

the use of strong active voice is a great way that encapsulates the entity of

the factors that we have discussed so far in the course of this document.

When truly taking into consideration the correct application of all of these

procedures in regards to effective technical writing, the technical writer

automatically ensures that their writing empowers a diverse range of

readers. Providing a sense of empowerment that is directed to the user,

helps them to use plain language themselves and considerate terminology.

This way, the technical writer ensures that they produce effective technical

documentation that is available for everyone everywhere they are.

As a technical writer, the focus should always be to build trust and

credibility on your work, so by conducting technical writing that is directly

supported by guidelines, the writer automatically contributes largely in

granting the users with a strong sense of trust and credibility in the written

work. When you present the information in a way that makes sense to the

reader and as a result provides them with the necessary means to act

accordingly in relation to technology and processes, the writing is a bridge

that fosters a positive relationship between the writer and the reader.
 57

And last but not least, technical writing is meant to support lifelong

learning, because it should inspire the reader to update their knowledge,

connect to the technology by embracing the positive effect that it has in

their life. For the writer, technical writing is a lifelong journey consisting of

consistent learning which leads to self-improvement and professional

growth.

4. TECHNICAL LANGUAGE AND JARGON

This chapter will provide information on the technical language that is a

factor of the technical documentation process along with the use of jargon.

It will cover a wide array of understanding that is related to the process in

particular as well as provide an exploration of the significance that these

factors have when writing for software.

 58

I want to start this chapter on a nice foot by primarily referring to the

technical language that is used in writing technical materials as the

language of innovation. And I say this mainly because of the effect that the

implication of this language has in continuously evolving to meet as well as

accommodate emerging concepts and technologies, all of which the

technical writer is continuously in the midst of. By defining the language in

this sense, I also imply humanity's constant pursuit of understanding of the

world around us by taking into consideration different aspects in which

reality presents itself to us. Through this language we are able to grasp a

firm understanding of the world of technology. Lastly, this language is a

testament of our capacity as beings, to adapt, learn and most importantly

continue to create and solve problems.

As a technical writer I have always considered technical language to be an

art form that is very heavily characterised by precision and conciseness. So

to support that argument I will happily draw the analogy that precision and

conciseness in the writing of the technical writer are very much the same as

the brush strokes of the painter on the white canvas or the musical notes of

a composer. There is definitely a craft that is required in order for a

technical writer to be able to distil complex ideas into common

understanding, so technical writing for me is a form of artistry that resides

within the realm of language.

 59

Technical writing has always served as a bridge of expertise, because it

provides the necessary means that allows a direct connection between

experts and those that are seeking to understand. What essentially happens

in the process of technical writing is that experts who possess deep

knowledge are connected with those who seek to learn through words. So

when functioning properly, this process enables a direct and effective

transference of ideas that always aim to foster a sense of understanding in

the common pursuit of knowledge.

What I intend to deeply focus on during the course of this chapter is the

quest of universality that is tied to technical writing as a concept, so by

doing that I wish to also attempt, to the best of my abilities, answer some

long standing questions that have not been previously completely answered.

Such questions play a major role. To accomplish such a challenging task it

is very important that we first acknowledge that technical writing at its very

core does in fact attempt and aspire to be universal. The means in which it

is carried out by different technical writer does set the tone however in

efforts that are made for it to transcend linguistic differences, and to be

able to foster a global dialogue on technology. It is also necessary to

mention here that significant contributions are continuously being made by

technical professionals that are engaged in the production of technical

documentation that aspires to push these ideas forward. However, what

remains challenging yet is that we are still dealing with a linguistic paradox
 60

of isolation that happens in technical writing, this isolation usually comes as

a result of the use of indirect language which is unnecessary and sets us

back decades in our progress. So to answer the question, I propose a

standardised means of language conduct that transcends cultures,

knowledge levels and also linguistic languages. This can be achieved

through the use of similar resources to conduct these means of progress. I

am also very much aware that there might be other approaches that other

technical writers might take, which can also prove more effective, however

the quest to conduct structured means that allow us all to transmit

information on a unified way still remains a quest for all of us in the

technical writing field.

By exploring such long standing concepts I cannot help but explore the

paradox of inaccessibility that arises in technical writing. The real journey

of understanding in relation to these concepts begins very simply by

realising that there is indeed a paradox that happens when conducting

means of technical writing. This can be further classified in the sense that,

it is very true that primarily technical language empowers those who

understand it, but it also very possible that it can provide deep isolation to

those who are not familiar with making them fail to understand it as a

result. Experience and continuous work on the field has proven that such a

paradox is very prominent, and that it should inspire us to push forward to

 61

find means that would in turn allow us to find ways that make technical

information very easily accessible while maintaining its precision.

An area that I think does not get enough academic attention is the wide

area of interpretation and its role in delivering correct and effective

technical writing. It has always fascinated me, to find out more information,

be that both theoretical or even practical that would primarily come as a

result of my work. To me, interpretation has always been the focal bridge of

understanding that falls between the words and the ideas that they

represent. So, by taking into consideration this definition I have always seen

it as crucial to continue exploring the interpretation of my writing itself.

Such an observation has led me towards grasping the truer and fuller

meaning behind the jargon that is transferred and allowing me to dive even

deeper on the unexplored levels of the interpretation so that I would be able

to uncover the true essence of the innovation I happen to be writing about.

I have referred to the use of technical language as a language of innovation

very early on in this chapter. Therefore, I want to reserve the means to

delve into that definition by presenting yet another layer of understanding

in relation to technical language, I want to do this so as to truly reflect the

multifaceted nature of the concepts that we have dealt with so far, and my

sheer desire to explain them correctly so as to provide factual information

that is understood by anyone who happens to read this document, presently

 62

or in the distant future. So, technical language for me presents itself as a

language of progress as well, because of the sole reason that it reflects the

collective pursuit of humanity towards progress. Now, progress has always

proved to be very crucial when considered in the technical context, because

of the contextual demands that are placed upon these concepts by the very

rapid development of technology itself. Having stated that, I think that this

characterization is essential in obtaining an even truer sense of the

technical language that is used.

Language should always aim to unify, so in this very instance it should

encapsulate the cumulative wisdom of generations, where each part when

used correctly, directly contributes to the evolving lexicon of innovation. It

is very safe for us to go ahead towards taking into account the ethical

considerations that are directly tied with the use of technical language and

jargon in the writing process. Firstly, what needs to be established is that

technical writers have ethical responsibilities when using technical

language to communicate with their readers. So it is very important as has

been stated numerous times during the course of this document, to

communicate with precision and transparency. Inaccuracies in technical

language can lead to very serious misunderstandings, therefore the

technical writer has a duty to adhere to clear and honest communication.

 63

When studying the evolution of technical language, technical writers have

also taken into serious consideration and evaluated the heavy implications

that technical language possesses in relation to helping humanity

understand reality better. This serious observation stems from the fact that

we as beings are always hungry for knowledge and understanding of the

intricate factors that lie all around us. Approaching technical language

from this standpoint has granted many technical writers to produce

astonishing technical works that explain large complexities that surpass the

realm of technology as well. Such a diverse application of this very simple

language proves, once more, what we have known all along to be very true,

and that is that when provided with the right tools of communication,

technical writers can bridge the gaps of knowledge in our ever-evolving

pursuit of knowledge.
 64

5. REVIEW AND REVISION

In this chapter I want to shed much needed light into exploring the review

and revision process when developing software oriented documentation. As

contributing concepts I wish to also explore and explain different types of

reviewing and editing techniques in technical writing. To be able to provide

a complete illustration of this process, I must go forward with applying

different levels of understanding, that aim to help technical writers that

consult this material to stay informed in correctly following these practices

described herein.

So to start with the explanation of the interactive yet very important

process of review and revision I want to first present iteration as a

philosophical concept but with direct applications in the realm of

technology. To do so, I want to go ahead and explore the implication that

the interactive process has in relation to continuous development of

software documentation. What we need to understand in relation to this

process that the technical documentation must go through, is to keep in

mind that technical documentation undergoes iterative decisions, and this

 65

remains the same independently from the software development

environment. What happens when the review process starts is that it

becomes very clear that each editing cycle brings us closer to clarity and

perfection. So really, the basic purpose of the process is to reveal hidden

insight that can be found within the technical documentation that is being

developed.

When consulting any kind of documentation, depending on the scope or size

of the documents that are under consideration, reviewing always ensures

that the documentation remains accurate in the presentation of knowledge,

clear in transferring information as initially indeed and stays true to the

needs and expectations of the readers. By always following guidelines that

ensure the successful completion of every step in the document

development process, we also have to make sure that the intended and

authorised personnel carries out editing operation towards the

documentation at hand. So to further categorise, usually the editing

operations are carried forward by technical experts, other technical writers

that are engaged with the project as well. By allowing different individuals

to edit the documentation we ensure that they each bring valuable insights

and fresh perspectives that help in improving the document. So by

effectively catching mistakes that are present in the document and

suggesting improvements, the document will continue to uphold its integrity

and value of information contained within.

 66

When referring to document changes, I want to explore the means that

changes and suggestions during the reviewing process are documented.

This step is very important as it directly contributes towards fostering a

strong basis for version control and helps with information governance in

the long run, making it easier to manage the documentation. In order to

establish a clear philosophy of progress that enables version control to be

applied seamlessly into this process, the technical writer is able to easily

allocate the flux of changes and the suggestions that the document receives

once it is published for review. Directly applying effective means to track

said changes promotes clarity in your documentation. Once established, it

ensures that all those who read it will understand it easily. That is precisely

why as a process, reviewing consists of effectively looking for any confusing

parts consistently and with great care towards the written word.

Consistency in the review process is of paramount importance, because it

ensures that the entirety of the documentation looks and sounds the same, a

vital part of this process is ensuring that the document meets the required

formatting entirely. When ensuing that the required consistency standards

are met in relation to the document, what follows is the process of testing

the document for usability. Generally, this process is considered helpful to

ensure that the readers are able to clearly understand and follow the

documentation design easily. Several levels of testing are conducted to

 67

ensure that the document meets usability standards before being published

for the readers.

It greatly helps, if during the reviewing process of the documentation, the

reviewing staff is taken seriously. This comes as a fact that reviewers

provide a very valuable perspective towards the improvement of our work.

Or if we happen to be reviewers of our work we must as technical writers

go to great lengths so as to ensure that we follow the same process of

reviewing and are not biased towards our own work. Another fact is the

quantity of the documentation that is being reviewed, it is a process that

does consume a significant amount of time as well as other resources.

Applying different levels of reviews when working with large documentation

is usually the right thing to do because each round catches different issues

with the document, and the goal of this process it to simply make the

documentation better with each pass.

Lastly, I wish to declare that when reviewing my own or other technical

writers' documentation I aim to always employ a refined sense of a

philosophy centered around improvement, and I encourage other technical

writers to do the same. To me, this philosophy simply means to keep

striving for continuous improvement, documentation should always be

updated to help users better.

 68

The review process is very important in the document development process

therefore it is mandatory that such a process is conducted according to

strict editorial guidelines that enable direct peer review and establish

appropriate channels for feedback incorporation.

6. REFLECTION ON TECHNICAL DOCUMENTATION

This process manual has provided the reader with a broad range of

information regarding the best writing as well as technical documentation

practices and guidelines that must be adhered to in order to be able to

produce effective technical documentation. In its entirety it has fulfilled its

intended purpose of serving the necessary information to other technical

writers who wish to subscribe to these processes and hopefully apply them

to their own work in the future, so as to continue direct and honest

information transference.

This section will allow us to yet again delve deeper in the concepts that we

have treated thus far. I want to once again put very strong emphasis on the

importance that clarity poses when writing technical documentation, and

here I wish to also state that the entire fundamental purpose of the

necessary factor of clarity in technical writing is simply to seek truth and

understanding. Technical writers will always continue to seek clarity and

truth in complex ideas. I have also gone on to draw clear implications of

 69

what really makes powerful technical writing, and how I firmly believe that

good and clear writing is a much needed tool to continue pushing forward

for individual as well as collective progress in technology.

It is the moral obligation of the technical writer, and I want to repeat this

many times because it is still very true, to be honest in their writing, to fight

for transparency, to believe in direct and simple communication and to,

above all, protect their work. It is very necessary that the technical writer

has a strong sense of integrity and respect wards their own work, because

the written words that they put onto the paper directly translate themselves

into a manifestation of human pursuit for knowledge, it is through effective,

clear and informative writing that we get to educate the world. We invite

people into the world of technology, to hopefully allow them to explore, and

broaden their horizons.

Yet something else that deserves an important space in this section is

without a doubt, a mention of the art of communication, without which

there would be no clear words to read and no chances to understand even

the most complicated of ideas in a way that stays with you forever. There

would be no documentation that crafts language to convey precise

information, so let us reflect on the power of language, the power of words

in shaping our reality, our world and most importantly our minds.
 70

My biggest wish as a technical writer would be that my work entices an

ongoing dialogue in all technical circles, as has been previously stated at

the beginning of this document. I want to inspire the immortal relationship

between the reader and the technical writer to keep on growing, never to

stop. And I wish that the reader always feels welcomed in my words.

Through the pursuit of the truth and a better life through technology we are

able to provide accurate and verifiable information, where as a final result

we realize that documentation is not just a practical guide, but a

manifestation of human values and understanding.

You have successfully reached the end of this technical documentation,

what follows next are annexes that the technical writer has seen important

to be included as means of providing additional information in relation to

this document.

May we stand together for clarity, and the truth - Lundrim Lluga, Technical

Writer

ANNEX A: WRITER’S RIGHTS AND DOCUMENT CONDUCT

This annex aims to outline the rights of the technical writer in relation to

the presented material, concepts, ideas and work processes within this
 71

document. It will emphasise the correct protection of their intellectual

distributions as well as integrity. Furthermore it provides clear information

on the expected conduct of this document from other entities.

The writer of this document states that all of the content presented within

this document, which includes text, images (if applicable), use of diagrams

(if applicable) must not be distributed, printed, copied or reproduced.

Should there be a need to use the content of the documentation in whole or

in part, it must only be done so if the written permission from the writer has

been granted.

This documentation is a product of the technical writer’s experience in the

field, therefore all processes, concepts and personal observations are and

must continue to be the technical writer’s intellectual property, they are

entirely original and present the technical writer’s approach towards the

role. However, the technical writer reserves the right to allow this

document’s use for eventual company projects, under the condition that the

technical writer is properly informed by standardized communication that

such a request has been made by the corporate or organizational entity.

Should such an event take place, the technical writer asks that the

permission is requested and that details of the intended use are clearly

stated.
 72

Should you have questions, or need more information regarding the use of

the documentation at hand or material presented, please contact the

technical writer at lundrimllugaa@gmail.com You can expect a reply after

twenty four hours have passed from your submission.