Lesson Proper for Week 1
4.1. Objective 1. TECHNICAL DOCUMENTATION
technical
Technical describes a specific art or science, or training for a particular job. If you have trouble with your
new computer, you might call for technical support, but a technical school teaches you a certain craft,
like how to weld.
Technical comes from the Greek tekhno, which means "art or skill." Anything technical requires both art
and skill. If you're an Olympic gymnast, you have technical abilities. You might go to a technical school to
learn how to be a chef, a mechanic, or a massage therapist. While being technical can be a positive trait,
you don't want to overwhelm someone with technicalities. For example: If you're trying to explain how a
car works to a kid and you start talking about manifolds, you're getting too technical.
document
A document is a piece of paper that contains official information. Don't you wish you had a document
saying that the bank owed you $5 million?
Document comes from the Latin verb meaning "to teach," so a document instructs you with the
information it contains. Legal documents such as contracts contain instructions on how the people signing
it will act. Passports, driver’s licenses and birth certificates are all official documents. As a verb, document
means "to record in detail," or "offer supporting evidence for." If you call a company to complain about
something, make sure to document your phone calls by noting the date you called, who you spoke to and
what was said
1.3. What is Technical Documentation?
The technical documentation term refers to different documents which contain product-related data and
information that will be helpful for users. Technical documentation contains product definition and
specification, quality assurance, manufacturing, description of features and functions, maintenance
information, and more.
The goal of technical documentation is to provide enough information for a user to understand the inner
and outer dependencies of the product at hand. It also helps users:

Troubleshoot their issues.


Find the best ways to use a product.
Learn the product from scratch and more.
Technical documentation is not just manuals, it also includes science papers, research, reports, white
papers, case studies and the like. You can find more information on types of technical documentation
here: ‘Types of Technical Documents’.
Usually, technical documentation was created in a printed version but nowadays it’s created online
as tech writers use HATs for this purpose.
4.2. Objective 2-3. General Classification
One of the main requirements for a technical document is its orientation for the intended audience.
According to the target audience, technical documentation is divided into two main types:
Process Documents. These describe the development, testing, maintenance and improvement of
systems. Process documents are used by managers, engineers, testers, and marketing professionals.
These documents contain technical terms and industry-specific jargon. Examples of this type of
documents include API, SDK and code documentation; internal development documentation, etc.
Some Examples of Process Documents
1. API (Application programming interface)
external
-is a set of functions that allows applications to access data and interact with
software components, operating systems, or micro-services.
2. SDK (Software development kit)
that
is a set of software tools and programs provided by hardware and software vendors
developers can use to build applications for specific platforms.
User Documents.
This type of documentation provides customers with the information they need in order to use the
product. User documents contain primarily instructional and explanatory materials. These documents use
everyday terms instead of technical jargon so that they are clear, concise and helpful even to novice
readers. Step-by-step walkthroughs, user guides, troubleshooting documentation may serve as examples.
Some example of User Documents
1. User Guides
or
It is essentially a book-length document containing instructions on installing, using,
troubleshooting a hardware or software products.
2. Troubleshooting documentation
It is a process of searching for the source of a problem in order to solve it
Technical Documentation VS User Documentation
Don’t you know the difference between technical documentation and user documentation? If not, then
you’ve opened the right article. Here, I will explain the difference between the two.
What is User Documentation?
User documentation is created for end-users on using a product. The main goal of user documentation is
to assist the end-users by providing them with clear and comprehensible info about the particular product
or service.
User documentation comprises:

Support Portals

FAQs

Video tutorials


Step-by-step guides
Embedded assistance
Tech writers describe the following aspects in user documentation:

Software requirements.

Installation guide.

How to start the system?

How to use features of products?

Screenshots explaining those features.

Contacts of the developer if an undocumented question arises and more. Tech writers create
technical documentation as well as user documentation.
What are the differences? Here they are:

Technical documentation is a broader term than user documentation.

Technical documentation can be internal and external, while user documentation is always created
for end-user.

The process of creating user documentation requires a minimum technical background compared
with technical documentation.
Click https://drive.google.com/file/d/1UiiVEHORQcNSwDV431pENj5nb4a-I0Ia/view?usp=sharing link to
open resource.
Lesson Proper for Week 2
Advanced Examples of Technical Documentation
The number of classifications and lists of technical documents is endless. While creation of presentations
or general reports requires no specific knowledge, some technical documents are rather complicated.
Below we’ve listed some of most advanced and widespread, in our opinion, examples for you to learn a
bit about them:
User Guide (Manual)
is a technical communication document (as well as the rest of this list) intended to assist users of a
particular system. Mainly focuses on tasks that can be done through the GUI. The language used is
matched to the intended audience, with jargon kept to a minimum or explained thoroughly.
Release Notes
are technical documents distributed with software products that contain bugfixes and added features.
They are usually shared with end users, customers and clients of an organization.
API (Application Programming Interface) Documentation
describes what services an API offers and how to use those services, aiming to cover everything a client
would need to know for practical purposes. It is traditionally found in documentation files but can also be
found in social media such as blogs, forums, and Q&A websites.
SDK (Software Development Kit) Documentation
is a complete set of APIs that allows you to perform almost any action you would need for creating
applications as well as other tools for developing for the platform that it is for. All SDKs are/contain APIs
but not all APIs are SDKs.
Market Requirements Document (MRD)
is a technical document that expresses the customer's wants and needs for the product or service. It
usually explains who the target audience is, what products are in competition with this one, why
customers are likely to want this product.
User Requirements Document (URD) (User Requirements Specification)
is a technical document that specifies what users expect the software to be able to do. The information
documented in a URD is meant to spell out exactly what the software must do, and becomes part of the
contractual agreement. A customer cannot demand features that are not in the URD, whilst the developer
cannot claim the product ready if it misses an item of the URD.
Other examples of advanced technical documents may include Architecture and Engineering Documents
(A&E Docs), help files, Standard Operation Procedure (SOP) manuals, installation guides, troubleshooting
guides, system configuration guides, code documentation, how to’s, reference sheets, white papers,
FAQs, Q&As, reference sheets, etc.
How to Write an "Architectural and Engineering Specifications (A&E)" Document
By Ugur Akinci | September 22, 2010
© Ugur Akinci
If you think A&E stands for “Arts and Entertainment” TV channel you’re correct. But it also stands for a
frequently used technical document: “Architectural and Engineering Specifications (A&E)“.
The adjective “architectural” here of course has nothing to do with buildings. It denotes the way
something is designed and structured. It’s used in the generic sense of the term.
Every hi-tech manufacturing or software company uses at least one A&E specification
document which is also referred to as an “A&E sheet”. Don’t be confused when you read “this sheet” or
“that sheet.” Basically they all refer to a “specification document” like A&E.
A&E is an interesting document, closer to a “design spec sheet.” It includes detailed
technical/engineering characteristics of the proposed product. The engineers need to agree on this
important document before they can start building/manufacturing the product in question.
Its difference from an MRD (Marketing Requirements Document) or a “functional spec sheet” is that A&E
does not describe how the product will be used and which functions it will perform and how it’ll meet a
specific user need. Instead, it focuses specifically on the technical characteristics that will make the
product or gadget work properly.
A&E document is always written in future sense because it describes a product that is still in the initial
design phase. That’s why you’ll see a lot of “shall“s in an A&E sheet.
For example, an A&E for an amplifier would include a lot of detailed information about power settings,
voltage requirements, the significance of different colors displayed by LEDs and light indicators, cooling
fan characteristics, rear panel connection terminal list and characteristics, etc.
A CCTV (Closed Circuit TV Camera) A&E might include camera mount type and dimensions, network
interface connector type and characteristics, image compression characteristics, user configuration
characteristics, image transfer bandwidth and recording characteristics, video and audio requirements
that the camera should satisfy, power requirements, computer terminal system requirements, etc.
Here are a few A&E spec samples:
help system (help file)
A help system (sometimes called a help file ) is a documentation component of a software program that
explains the features of the program and helps the user understand its capabilities. A bit like an
extensive, organized, and thorough collection of FAQ s (frequently asked questions), the help system's
purpose is to provide the answers that a user needs to understand to use the program effectively.
What Is a Standard Operating Procedure?
A standard operating procedure, or SOP, is a step-by-step set of instructions to guide team members to
perform tasks in a consistent manner. SOPs are particularly important for complex tasks that must
conform to regulatory standards. SOPs are also critical to ensuring efficient effort with little variation and
high quality in output.
Why Do We Need Standard Operating Procedures?
Standard operating procedures, including procedures, workflows, and work instructions, enable good
communication and promote consistency in processes and output. SOPs help team members work toward
common goals. Managers, team members, and consultants can come together to build processes and
document those processes. SOPs, in conjunction with regular training and feedback, guide teams to
success.
SOPs are important in clinical research and practice, such as in pharmaceutical processing. In these and
other areas, SOPs bolster processes that require triage, segregation of origins, or tracking of cause and
effects. In clinical settings, well-prepared SOPs can save an organization from FDA warnings and Form
483 sanctions. The international quality standard ISO 9001 requires companies to document
manufacturing processes that can affect the quality of output.
How to Write a Software Installation Guide
© Ugur Akinci
An installation guide is written to describe the installation of either a mechanical/electronics system (like
a child’s swing or a hi-fi set) or a software product. Here we will focus mainly on the latter.
A software installation guide overlaps with System Administration Guide since it covers similar
configuration tasks. That’s the reason why the demarcation line between these two guides may not
always be very clear.
Overlap Between Different Types of Guides
As you can easily tell, some of the above information can be included in a User or System Administration
Guide as well. The decision what information should go where is a management (or client) decision
although, if you are the writer, you can argue your case as well. However it is much better to repeat
crucial information in more places than one since you usually have no control over the way technical
manuals are used.
For example, you can ASSUME that a customer would refer to the Installation Guide to understand the
meaning of System Error Codes but perhaps he or she won’t. Perhaps your customers will only read the
User Manual and if the troubleshooting information is included only in the System Admin or Installation
guide, they’ll pick up the phone and call your service center to solve a simple problem instead of referring
to the Installation Guide.
So, when in doubt, include important information in more guides than one despite the risk of redundancy
and repetition.
What does System Configuration (SC) mean?
System configuration is a term in systems engineering that defines the computer hardware, the processes
as well as the various devices that comprise the entire system and its boundaries. This term also refers to
the settings or the hardware-software arrangement and how each device and software or process
interact with each other based on a system settings file created automatically by the system or defined
by the user.
System configuration mainly refers to the specification of a given computer system, from its hardware
components to the software and various processes that are run within that system. It refers to what
types and models of devices are installed and what specific software is being used to run the various
parts of the computer system. By extension, system configuration also refers to the specific operating
system settings that have been set by default automatically or manually by a given program or the user.
A computer system, particularly the operating system, dictates a set of default settings and configuration
when the system first comes online. These settings dictate the normal function and features that make
the system run in a stable manner. To this end, operating systems have their own configuration utilities
to allow administrators or users to change the configuration of the system. For Microsoft Windows, this is
called the Microsoft System Configuration Utility or "msconfig."
Good Documentation Comes in Many Forms
When most developers think of code documentation, they think of comments. Comments can be valuable
additions to code, but they’re not the only definition of documentation. Documentation is anything you
write in addition to your code to help someone else understand how it works. You might not think of it
this way, but a good example of code documentation is a README file. A good example of basic
documentation is the Express.js README file. It answers several important questions about the
framework and tells you how you can include it in your project, how to install it, and how to run tests.
Good documentation can come in the form of API documentation too. Once again, Express.js provides
a great example. This version of documentation is more of a reference library for developers using the
framework. You’ll find answers to questions about what individual functions do and what different
parameters to those functions mean. Without that quality documentation, Express wouldn’t have nearly
as many teams using it as they do.
And of course, you can use in-line comments to document code too. Those kinds of comments usually
aren’t used to teach people outside of your own team about the code. Instead, they’re useful to explain
what’s happening in a particular bit of code to your teammates or to your future self.
Why You Should Document Your Code
As noted above, many developers don’t understand the purpose of code documentation. They’ll argue
that good code should be self-documenting and that you shouldn’t need to explain it. These people are,
in a word, wrong. The truth is that good documentation is an essential part of any code base. Why?
Because people shouldn’t need to read all of your code in order to understand what it does. “People” in
that previous sentence can refer to anyone, including your future self.
The truth is that often, the “people” who’ll need to understand code after it’s written is you. That little bit
of logic that seemed so clever when you wrote it six months ago might be difficult to understand today.
If your code is well-documented, you don’t need to spend time trying to understand what it does. You’ll
be able to spend a few seconds looking at the description and then get back to what you’re working on
right now.
If you’re lucky enough to be working on code that’s used by dozens or hundreds of developers, good
documentation is even more important. Your users’ lives will be significantly improved by your time spent
writing good documentation, and they’ll thank you for it. Literally!
The key to remember is that good documentation saves more time than it takes to write it. It might be
your time, or it might be the time of team members, or even people you’ll never meet. Sometimes,
writing documentation will even help you recognize a part of your code that’s too complicated so you can
simplify it.
Reference Sheets
Purpose
The purpose of a reference sheet is to have a list of people who can verify and elaborate on your
professional experience for a potential employer. Past employers, professors, and advisors are the best
professional references to have. It is important to have a reference sheet because potential employers
will often ask for a list of references they can contact. If you included a statement such as "References
Available Upon Request" on your résumé, you should be able to produce a reference sheet as soon as
one is requested. In any case, having a reference sheet will save you time later on during the interview
process.
Things to remember
Make sure to include people who know what type of person you are and who are familiar with your work.
It is important to select individuals who know your distinctiveness so that they can provide a positive and
accurate description of you to the employer or company in which you are seeking employment. You
should ALWAYS contact your references before including them on a reference sheet. It is also a good
idea to give them a copy of your résumé and talk to them about the job you are seeking so they will
know how to best represent you.
What to include

Your name

Your present and permanent address(es)

Your reference person or persons' information, which includes that person's:
o
Name
o
Department/Company
o
Title/Position
o
Address
o
o
Telephone number
Brief statement as to how you know this person.
What is a White Paper?
Originally, the term white paper was used as shorthand to refer to an official government report,
indicating that the document is authoritative and informative in nature. Writers typically use this genre
when they argue a specific position or propose a solution to a problem, addressing the audience outside
of their organization. Today, white papers have become popular marketing tools for corporations
especially on the Internet since many potential customers search for information on the Web.
Corporations use white papers to sell information or new products as solutions that would serve their
customers' needs.
The Purpose of a White Paper
Typically, the purpose of a white paper is to advocate that a certain position is the best way to go or that
a certain solution is best for a particular problem. When it is used for commercial purposes, it could
influence the decision-making processes of current and prospective customers.
What Kind of Problems Do Readers Want to Solve?
The audience for a white paper can be the general public or multiple companies that seek solutions to
their problems or needs. Typically, you will not know your audience personally, unlike when you write a
recommendation report for your client. And yet, in order to persuade your audience, you need to focus
on their needs. If you can address the problems that your readers want to solve, they will read your
white paper for a solution. Otherwise, your white paper may not be read. It is important to emphasize
your readers' interests rather than your interests, as shown in the example below:
Not: This white paper introduces ABC company's new freight service.
Instead: This white paper discusses how to choose a freight service company that best fits your needs.
How to Write an FAQ Page–with Examples

website tips

MAY 28, 2019

8 MIN READ
When you build a website, you probably think your homepage is the most important. But let me put a
case forward for the humble “frequently asked questions” page of your website—your FAQ. The best FAQ
pages do a lot of the heavy lifting on your website. They’re one of the best ways to acquire new
customers, close sales, and save time answering repetitive questions.
Yet this list of commonly asked questions is usually overlooked or treated as an afterthought. No more!
Read on for tips on how to write an FAQ section and some of the reasons why it will help your business!
What does FAQ mean? It stands for frequently-asked questions, and it’s a page on a website that
gives quick answers to customer questions. The idea is to keep the answers short and direct so that
people find info quickly. We write it as “an FAQ”…(“an eff-ay-cue”) instead of “a FAQ” (a “fack”).
What’s the benefit of an FAQ section on your website?
1. It saves you time. If you spend a lot of your time answering emails or social media queries, an
FAQ can be a real timesaver. It can also help prevent costly and time-consuming returns in your
online store.
1. It brings new website traffic and new customers. Google’s goal is to deliver answers to
questions. If you put your text in a Q&A format, you’re doing half the work already. Even better, if
you have a good answer to a question, you might get featured in one of Google’s answer boxes or
feature snippets, which will give you a big traffic boost.
1. It builds trust and shows that you get it: A well-written FAQ page shows experience. You
know what customers are thinking and you’ve already got an answer. It’s a great way to increase
the trust and professionalism of your website.
Q&A
A Q&A is one of the simplest methods of sharing an interview with an audience. It is essentially an
edited transcript of an interview that includes both the interviewer’s direct questions and the
interviewee’s response in written format. Unlike feature stories, Q&As have little room for “fluff.” They tell
the message of your interviewee without a narrative story. Many people prefer Q&As because of their
easy readability and to-the-point structure. Due to the simplistic nature of the Q&A, it is important to
focus on the presentation of the final product. Here are seven simple tips to consider when writing a
Q&A:
1. Think about the final product before conducting the interview. This includes brainstorming
questions that call for an open-ended response. It is very hard to formulate a good Q&A with
simple “yes” or “no” questions. For example, the question “Do you like dogs?” doesn’t leave much
room for an explanation on the subject. Consider changing it to, “What do you like most about
dogs?” to give the interviewee a chance to elaborate on the topic.
2. Type out the entire transcript before editing. This is the easiest way to begin formatting the
final piece. Listen to the interview and type out word-for-word the questions you asked and the
responses you received. This will help you figure out the best way to arrange the results.
3. Arrange your questions and answers in an order that makes sense. The goal here is to
make the piece as easy to navigate as possible. Try your best to keep your questions in a good
flowing order by not jumping around topics. It should all flow as a typical conversation would.
4. Feel free to edit what your interviewee says without changing their meaning. Most
people don’t speak how we professionally write. It’s okay to edit out your interviewee’s “ums,”
“uhs,” and pauses, as long as you don’t change the meaning of their words.
5. Re-listen to your interview after completing your Q&A write up. This will ensure that you
haven’t missed any important information that could benefit the piece. Perhaps after re-listening,
you realize one of the questions you’ve included in the written version doesn’t necessarily pertain
to the interview as a whole. In this step, delete any unnecessary questions and answers.
6. Formatting is key. It may seem simple, but formatting in a Q&A is essential. It’s important to
keep your formatting consistent. For example, you may choose to format your Q&A like this:
Lesson Proper for Week 3
FORMS OF TECHNICAL DOCUMENTATION
PATENT
A patent is a form of intellectual property that gives its owner the legal right to exclude others from
making, using, or selling an invention for a limited period of years in exchange for publishing an enabling
public disclosure of the invention. In most countries, patent rights fall under private law and the patent
holder must sue someone infringing the patent in order to enforce his or her rights. In some industries
patents are an essential form of competitive advantage; in others they are irrelevant.
The procedure for granting patents, requirements placed on the patentee, and the extent of the exclusive
rights vary widely between countries according to national laws and international agreements. Typically,
however, a patent application must include one or more claims that define the invention. A patent may
include many claims, each of which defines a specific property right. These claims must meet relevant
patentability requirements, such as novelty, usefulness, and non-obviousness.
What are the different types of patents?
Different types of patent applications exist so that inventors can protect different kinds of
inventions. Savvy inventors can utilize the different kinds of patent applications to secure the rights they
need to protect their inventions. There are four different patent types:
·
A UTILITY PATENT is what most people think of when they think about a patent. It is a long,
technical document that teaches the public how to use a new machine, process, or system. The kinds of
inventions protected by utility patents are defined by Congress. New technologies like genetic
engineering and internet-delivered software are challenging the boundaries of what kinds of inventions
can receive utility patent protection.
·
A PROVISIONAL PATENT goes hand in glove with a utility patent. United States law allows
inventors to file a less formal document that proves the inventor was in possession of the invention and
had adequately figured out how to make the invention work. Once that is on file, the invention is patent
pending. If, however, the inventor fails to file a formal utility patent within a year from filing the
provisional patent, he or she will lose this filing date. Any public disclosures made relying on that
provisional patent application will now count as public disclosures to the United States Patent and
Trademark Office (USPTO).
·
A DESIGN PATENT protects an ornamental design on a useful item. The shape of a bottle or the
design of a shoe, for example, can be protected by a design patent. The document itself is almost
entirely made of pictures or drawings of the design on the useful item. Design patents are notoriously
difficult to search simply because there are very few words used in a design patent. In recent years,
software companies have used design patents to protect elements of user interfaces and even the shape
of touchscreen devices.
·
A PLANT PATENT is just that: a patent for a plant. Plant patents protect new kinds of plants
produced by cuttings or other nonsexual means. Plant patents generally do not cover genetically modified
organisms and focus more on conventional horticulture.
WHAT ARE SPECIFICATIONS?
Specifications describe the nature and the class of the work, materials to be used in the work,
workmanship etc. and is very important for the execution of the work. The cost of a work depends much
on the specifications. Specifications should be clear.
Purpose of giving Specifications
·
The cost of an unit quantity of work is governed by its specifications.
·
Specification of a work is required to describe the quality and quantity of different materials
required for a construction work and is one of the essential contract documents.
·
This also specifies the workmanship and the method of doing the work. Thus specification of a
work serves as a guide to a supervising staff of a contractor as well as to the owner to execute the work
to their satisfaction.
·
A work is carried out according to its specification and the contractor is paid for the same. Any
change in specification changes the tendered rate.
·
As the rate of work is based on the specification, a contractor can calculate the rates of various
items of works in tender with his procurement rates of materials and labour. Thus tender rate without
specification of works is baseless, incomplete and invalid.
Specification is necessary to specify the equipment tools and plants to be engaged for a work and thus
enables to procure them beforehand.
The necessity of specification is to verify and check the strength of materials for a work involved in a
project.
Types of Specifications
General Specifications
In general specifications, nature and class of works and names of materials that should be used are
described. Only a brief description of each and every item is given. It is useful for estimating the project.
The general specifications do not form a part of contract document.
Detailed Specifications
The detailed specifications form a part of a contract document. They specify the qualities, quantities and
proportions of materials and the method of preparation and execution for a particular item of works in a
project. The detailed specifications of the different items of the work are prepared separately and they
describe what the work should be and how they shall be executed. While writing the detailed
specifications, the same order sequence as the work is to be carried out is to be maintained.
What is a Datasheet? Definition: A data sheet is a summary of technical product. It identifies the core
features, specifications, and other criteria that the reader will need to understand.
If this is your first time writing a data sheet, make sure you understand the purpose of datasheets before
you sit down to write.
Remember that a data sheet is not a sales document. It’s not a pitch. It’s not an attempt to persuade the
reader try your product — without giving them all the information they need. It’s the opposite.
The purpose of a datasheet is to give your readers the information they need to decide if this is the type
of product that might work for them.
This means that you have to be clear on your target reader, and what they will do with this document. If
not, you are likely to head off on the wrong tangent and write a different type of document, for example,
a fact sheet or a technical brochure. The technical documentation term refers to different documents
which contain product-related data and information that will be helpful for users. Technical
documentation contains product definition and specification, quality assurance, manufacturing,
description of features and functions, maintenance information, and more.
What’s the purpose of datasheets?
Data sheets are part of your software development product documentation, typically, the most technical
part.
Unlike technical specifications, brochures, and getting started guides, they provide a bare bones
description of the product, usually from a technical angle. Think of it as a snap shot of the product. No
hype. This is what it does.
Why do people read datasheets?
First, they don’t actually read them in the sense that they may not read each line super carefully.
Instead, they probably skim the datasheet looking for certain keywords, typically features they’re looking
for in your product.
When writing the data sheet, ask yourself: does my product have this feature?
If so, weave it into the document. Include different variations of the word or phrase, too.
Test Method
In software development, engineering, science, manufacturing, and business, its developers, researchers,
manufacturers, and related personnel must understand and agree upon methods of obtaining data and
making measurements. It is common for a physical property to be strongly affected by the precise
method of testing or measuring that property. As such, fully documenting experiments and
measurements while providing needed documentation and descriptions of specifications, contracts, and
test methods is vital.
Using a standardized test method, perhaps published by a respected standards organization, is a good
place to start. Sometimes it is more useful to modify an existing test method or to develop a new one,
though such home-grown test methods should be validated and, in certain cases, demonstrate technical
equivalency to primary, standardized methods.[6] Again, documentation and full disclosure are
necessary.
A well-written test method is important. However, even more important is choosing a method of
measuring the correct property or characteristic. Not all tests and measurements are equally useful:
usually a test result is used to predict or imply suitability for a certain purpose. For example, if a
manufactured item has several components, test methods may have several levels of connections:
·
test results of a raw material should connect with tests of a component made from that material
·
test results of a component should connect with performance testing of a complete item
·
results of laboratory performance testing should connect with field performance
These connections or correlations may be based on published literature, engineering studies, or formal
programs such as quality function deployment. Validation of the suitability of the test method is often
required.
What Is a Manufacturing System?
A manufacturing system is an approach to making products that is based upon several
factors. These include how much of the product is needed, how quickly the product must be
produced and how unique the product must be to ensure sufficient sales. Manufacturing
systems include custom, assembly, flexible, intermittent, reconfigurable, just-in-time and
lean manufacturing systems.
Custom manufacturing is the original form of production. It is the making of unique items,
one at a time, by employing the skills of a single craftsman. Craftsmen might work alongside
one another, but they do not work together as a team, because one person completes the
manufacture of an individual item.
This is in contrast with an assembly manufacturing system, in which each worker
contributes one or more actions that are required in the manufacturing process. This action
might be repeated every few seconds or for longer intervals, depending on the complexity of
the task. This also is referred to as a mass-production manufacturing system, and it typically
values speed and uniformity. The drawbacks to mass-production manufacturing systems are
the difficulty of assuring the correct supply of products in real time and being unable to
provide customized product offerings.
Flexible manufacturing proposes a solution to producing too much or too little of the
product. This method also enables a manufacturer to respond to consumer demand for
customized products. It is more expensive to tool a flexible manufacturing system.
Intermittent manufacturing, in which the same item is made repeatedly, might employ a
reconfigurable manufacturing system. This is so that different items can be mass-produced
one type of item at a time. There is a trade-off with flexible manufacturing systems. The
redundancy of functions in tooling systems adds costs in exchange for flexibility, so the
initial capital outlay might be higher.
The goal of just-in-time production is to eliminate inventory. Carrying more inventory than is
needed adds to overhead costs. For example, producing too many of a particular model of
automobile results in unsold vehicles depreciating on the car seller’s lot. The storage of
unsold items also can be costly in terms of space and money. Conversely, running out of
inventory adversely affects sales because customers will go to a competitor if a particular
item is not available when the customer is ready to buy.
What is Lean Manufacturing?
Ever since Henry Ford invented the assembly line, industrial innovators have constantly focused on
improvement through a variety of different manufacturing strategies. Lean manufacturing is a
manufacturing strategy that seeks to produce a high level of throughput with a minimum of inventory.
Originally a Japanese methodology known as the Toyota Production System designed by Sakichi Toyoda,
lean manufacturing centers around placing small stockpiles of inventory in strategic locations around the
assembly line, instead of in centralized warehouses. These small stockpiles are known as kanban, and the
use of the kanban significantly lowers waste and enhances productivity on the factory floor.
In addition to eliminating waste, lean manufacturing seeks to provide optimum quality by building in a
method whereby each part is examined immediately after manufacture, and if there is a defect, the
production line stops so that the problem can be detected at the earliest possible time. The lean method
has much in common with the Total Quality Management (TQM) strategy. Both strategies empower
workers on the assembly line, in the belief that those closest to production have the greatest knowledge
of how the production system should work.
In a lean manufacturing system, suppliers deliver small lots on a daily basis, and machines are not
necessarily run at full capacity. One of the primary focuses of lean systems is to eliminate waste; that is,
anything that does not add value to the final product gets eliminated. In this respect, large inventories
are seen as a type of waste that carries with it a high cost. A second major focus is to empower workers,
and make production decisions at the lowest level possible.
Answer key:
These are method for a test in science or engineering, such as a physical test, chemical test, or statistical
test. (Test method)
These are technical document that teaches the public how to use a new machine, process, or system.
(Utility patent)
These often refers to a set of documented requirements to be satisfied by a material, design, product, or
service. (Specification)
These are steps through which raw materials transformed into final product. (Manufacturing system)
These is a document provided with a product that lists various pieces of information about the product.
(Technical data system)
Lesson Proper for Week 4
Let's watch the you YouTube video "9 Point Checklist"
Play Video
Who is Technical Writer?
A professional writer who creates various types of technical documentation, helping people
understand how to use a product or a service. The examples of the documentation technical writers
create include: online help, user guides, online training material, white papers, design specifications,
project plans, business correspondence, etc. This documentation can be delivered to the end user both
as a printed version or as an electronic version.
In many organizations, the role of a Technical Writer is delegated to software developers,
support engineers, and quality assurance engineers.
What does a technical writer do?
A technical writer creates documents simplified technical documents that are easy to understand.
They write instruction manuals, guides, journal articles or other kinds of supporting documentation.
Technical writers often work for businesses organizing, creating and distributing technical documents.
Other responsibilities include:
•
Determining the best form of documentation for the project
•
Conducting research to gather information
•
Collaborating with technical professionals to understand products and
•
Editing the work of other technical writers
procedures
Technical writer requirements
Technical writers combine an understanding of technical concepts with the ability to write in a
way that is easy to understand. Many of the requirements for being a technical writer serve to
demonstrate these skills.
Education
To become a technical writer, you’ll need a bachelor’s degree in technical writing or a related
subject. Your coursework should include business writing, non-fiction writing and editing. It’s helpful to
take additional technological courses to prepare for a career in technical writing. You can also earn a
degree in engineering, computer science or other technical fields, then take courses in communications
and business writing.
Training
Companies will train technical writers on their specific content. Depending on the business, you
should receive training in the content and style in which you’ll need to write. You’ll learn more about the
types of software and computer programs the company uses as well. During training, you will gain an
understanding of the creation and delivery process of the written materials.
There are many technical writing conferences that you can attend to continue training. During
technical writing conferences, you can learn more about industry trends, styles of communication and
delivery methods. Gaining more knowledge in these areas will help you improve your work and excel in a
career as a technical writer.
Certifications
As technical writers work in a variety of industries, there are many institutions that offer
certifications, including:Society for Technical Communication (STC): The STC offers three levels of
technical writing certifications—Certified Professional Technical Communicator: Foundation, Practitioner
and Expert. As a Foundation CPTC, you show that you have the necessary knowledge to perform work as
a technical writer. Earning a CPTC at the Practitioner level demonstrates your ability to write technical
documents at an advanced level. The CPTC-Expert designates your proficiency in the subject. To obtain a
Foundation CPTC, you’ll need to pass an exam, while the Practitioner and Expert levels require you to
pass an exam and submit a writing sample for review.
American Medical Writers Association **(AMWA):**If you want to be a technical writer in the medical
field, you can earn a Medical Writer Certified certification from the AMWA. A MWC shows your ability to
write a variety of medical documents. To obtain a MWC, you need to have a bachelor’s degree and two
years’ experience in the medical communication field. You must also pass an online exam.
Technical writers typically have the following skills:
Writing: You need to have a good command of language to be able to describe complicated information
in clear and concise words. As a technical writer, you should be able to write for extended periods of
time.
Communication: As a technical writer, your work will involve collaborating with other coworkers and
clients to ensure you produce satisfactory material. The ability to communicate with others ensures you
can successfully work with others to write documents.
Problem-solving: Some projects require you to figure out how something works before you document
its function. You may also have to write how-to instructions. Strong problem-solving skills will help you
understand the topic you’re writing about so you can create simple documents.
Research: You should be able to explore technical topics and organize your findings in easy-tounderstand language. Conducting in-depth research can help you write more thorough instructions for
others.
Online publishing: Many technical writers write for websites and other online media. Depending on the
company, you may need to have experience with online publishing software or content management
systems.
Time management: Technical writers often work to strict deadlines, so you need to be able
to
manage your time well. You may also need to be able to write for different projects
concurrently, and strong time-management skills can help you stay on schedule for each project.
Top five characteristics of a successful technical writer
Which qualities make a successful technical writer? I believe they are the same qualities that
make a successful journalist. Both journalists and technical writers are non-fiction writers and non-fiction
writing demands a different skill set than fiction writing. After more than 15 years in this business, here
are my top five characteristics of a successful technical writer:
Organized – Organization should come naturally to you and you should enjoy doing it, because
technical writing is all about researching, culling, and organizing facts. You need the ability to put all
steps in a process in the correct order and ruthlessly discard irrelevant facts that don’t fit in. For example,
if you are writing instructions on how to install software, don’t include a history of the project or who
developed the software.
Simple – You need to be able to cut through the jargon of engineers and other subject matter experts
and translate their explanations into clear, concise terms that a non-expert can understand. My motto is:
“Unless I understand it, our customers won’t understand it.” Sometimes you will be mocked for doing
this, but your customers will appreciate it. You should use as few words as possible to convey the
information. Remember, simple is elegant!
Humble – Don’t be afraid to say, “What does that mean?” or “Can you show me?” – every day if
necessary. Don’t worry that you are the stupidest person in the room. The truth is, the person who never
learns anything new is the stupidest person in the room – and that won’t be you! When someone uses an
acronym, ask the meaning. Often the person using the acronym doesn’t even know; and if that happens,
look it up online. Chances are, other people in the room didn’t understand the acronym or explanation
just given by that expert either.
Tenacious – You must have the ability to grab hold of a problem or topic – like a bulldog – and not let
go until you have the answer. If an engineer does not have time to give you that product demo today,
ask if he will show you tomorrow. Then put it on your calendar and follow up every few days until you
get the demo.
Meticulous – If you are a “big picture” person and don’t care that much about accuracy and attention to
detail, you won’t make a good technical writer. If you say, “I can’t edit or
proofread my own work,”
you won’t make a good technical writer. The person who researches and writes the piece is often the
same person who edits and proofreads the piece. Many times, the only person checking what you write is
the subject matter expert, who cares about technical accuracy, but cannot correct writing style, format,
layout, spelling, grammar, and punctuation. If you don’t care about semicolons and fonts, find another
career. If no one has ever described you as “obsessive” or “picky,” find another
career.
Job Duties and Tasks for: "Technical Writer"
1) Organize material and complete writing assignment according to set standards regarding order, clarity,
conciseness, style, and terminology.
2) Maintain records and files of work and revisions.
3) Edit, standardize, or make changes to material prepared by other writers or establishment personnel.
4) Confer with customer representatives, vendors, plant executives, or publisher to establish technical
specifications and to determine subject material to be developed for publication.
5) Review published materials and recommend revisions or changes in scope, format, content, and
methods of reproduction and binding.
6) Select photographs, drawings, sketches, diagrams, and charts to illustrate material.
7) Study drawings, specifications, mockups, and product samples to integrate and delineate technology,
operating procedure, and production sequence and detail.
8) Interview production and engineering personnel and read journals and other material to become
familiar with product technologies and production methods.
9) Observe production, developmental, and experimental activities to determine operating procedure and
detail.
10) Arrange for typing, duplication, and distribution of material.
11) Assist in laying out material for publication.
12) Analyze developments in specific field to determine need for revisions in previously published
materials and development of new material.
13) Review manufacturer's and trade catalogs, drawings and other data relative to operation,
maintenance, and service of equipment.
14) Draw sketches to illustrate specified materials or assembly sequence.
Answer key:
TRUE - Many technical writers write for websites and other online media.
TRUE - One of the duties and job of a technical writer is to maintain records and files of work and
revisions.
FALSE - Some projects require you to figure out how something works before you document its
malfunction.
FALSE - As a technical writer, your work will involve disunion with other coworkers and clients to ensure
you produce satisfactory material.
TRUE - Technical writers often work to strict deadlines, so you need to be able to manage your time
well.
FALSE - You don’t to have a good command of language to be able to describe complicated information
in clear and concise words.
FALSE - To become a technical writer, you don’t need a bachelor’s degree in technical writing or a
related subject.
TRUE - As technical writers work in a variety of industries, there are many institutions that offer
certifications.
TRUE - A technical writer is professional writer who produces technical documentation that helps people
understand and usage of a product and services.
Lesson Proper for Week 5
SOFTWARE DOCUMENTATION
Technical Documentation in Software Development
Documentation exists to explain product functionality, unify project-related information, and allow for
discussing all significant questions arising between stakeholders and developers.
Project documentation by stages and purpose
On top of that, documentation errors can set gaps between the visions of stakeholders and engineers
and, as a result, a proposed solution won’t meet stakeholder’s expectations. Consequently, managers
should pay a lot of attention to documentation quality.
Agile and waterfall approaches
The documentation types that the team produces and its scope depending on the software
development approach that was chosen. There are two main ones: agile and waterfall. Each is unique in
terms of accompanying documentation.
The Waterfall approach is a linear method with distinct goals for each development phase.
Teams that use waterfall spend a reasonable amount of time on product planning in the early stages of
the project. They create an extensive overview of the main goals and objectives and plan what the
working process will look like. Waterfall teams strive to create detailed documentation before any of the
engineering stages begin. Careful planning works well for projects with little to no changes in progress as
it allows for precise budgeting and time estimates. However, waterfall planning has proven to be
ineffective for long-term development as it doesn’t account for possible changes and contingencies on the
go. According to PMI’s 9th Global Project Management Survey, the Agile approach is used by 71 percent
of organizations for their projects.
Systems Planning
The systems planning usually begins with a formal request to the IT department, called systems request,
which describes problems or desired changes in an information system or a business process. A systems
request can come from top managers, a planning team, a department head, or the IT department itself.
The request can be very significant or relatively minor. A major request might involve a new information
system or the upgrading of an existing system. In contrast, a minor request might ask for a new feature
or a change to the user interface.
The purpose of this phase is to perform a preliminary investigation to evaluate an IT-related business
opportunity or problem. The preliminary investigation is a critical step because the outcome will affect the
entire development process. A key part of the preliminary investigation is a feasibility study that reviews
anticipated costs and benefits and recommends a course of action based on operational, technical,
economic and time factors.
Systems Analysis
The purpose of the system analysis phase is to build a logical model of the new system. The first step is
requirement modeling, where you investigate business processes and document what the new system
must do to satisfy users. Requirement modeling continues the investigation that began during the
systems planning phase. To understand the system, you perform fact-finding using techniques such as
interviews, surveys, document review, observation, and sampling. You use the fact-finding results to
build business models, data and process models, and object models.
The deliverable for the systems analysis phase is the system requirement document. The requirement
document describes management and user requirements, costs and benefits, and outline alternative
development strategies.
Systems Design
The purpose of the systems design phase is to create a physical model that will satisfy all documented
requirements for the system. At this stage, you design the user interface and identify necessary outputs,
inputs, and processes. During the systems design phase, you also determine the application architecture,
which programmers will use to transform the logical design into program modules and code.
The deliverable for this phase is the system design specification, which is presented to management and
users for review and approval. Management and user’s involvement is critical to avoid any
misunderstanding about what the new system will do, how it will do, and what it will cost.
Systems Implementation
During the system systems implementation phase, the new system is constructed. Programs are written,
tested and documented and the system is installed. If the system was purchased as a package, systems
analysts configure the software and perform any necessary modifications. The objective of the systems
implementation phase is to deliver a completely functioning and documented information system. At the
conclusion of this phase, the system is ready for use.
The system implementation phase also includes an assessment, called systems evaluation, to determine
whether the system operates properly and if costs and benefits are within expectations.
Systems Support and Security
During the systems support and security phase, the IT staff maintains, enhances, and protects the
system. Maintenance changes correct errors and adapt to changes in the environment, such as new tax
rates. Enhancements provide new features and benefits. Security controls safeguard the system from
both external and internal threats. A well designed system must be secure, reliable, maintainable, and
scalable. Business processes change rapidly, and most information systems needs to be updated
significantly or replaced after several years of operation.
Agile Development Cycle
Agile development cycle scheme
The agile approach is based on teamwork, close collaboration with customers and stakeholders, flexibility,
and ability to quickly respond to changes. The basic building blocks of agile development are iterations;
each one of them includes planning, analysis, design, development, and testing. The agile method
doesn’t require comprehensive documentation at the beginning. Managers don’t need to plan much in
advance because things can change as the project evolves. This allows for just-in-time planning. As one
of the Agile Manifesto values suggests, putting – “working software over comprehensive documentation “, the idea is to produce documentation with information that is essential to move forward, when it
makes the most sense.
Agile development cycle scheme
Today, agile is the most common practice in software development, so we’ll focus on documentation
practices related to this method.
4.2. Objective-3. Types of Documentation
The main goal of effective documentation is to ensure that developers and stakeholders are headed in
the same direction to accomplish the objectives of the project. To achieve them, plenty of documentation
types exist.
Adhering to the following classifications.
All software documentation can be divided into two main categories:


Product documentation
Process documentation
1. Product documentation describes the product that is being developed and provides instructions on
how to perform various tasks with it. In general, product documentation includes requirements, tech
specifications, business logic, and manuals.
There are two main types of product documentation:
Product documentation describes the product that is being developed and provides instructions on how to
perform various tasks with it. Product documentation can be broken down into:


System Documentation
User Documentation
System documentation represents documents that describe the system itself and its parts. It includes
requirements documents, design decisions, architecture descriptions, program source code, and FAQs.
User documentation covers manuals that are mainly prepared for end-users of the product and system
administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation,
and reference manuals.
Process documentation represents all documents produced during development and maintenance that
describe… well, the process. The common examples of process-related documents are standards, project
documentation, such as project plans, test schedules, reports, meeting notes, or even business
correspondence.
The main difference between process and product documentation is that the first one record the process
of development and the second one describes the product that is being developed
Types of software Process documentation:
1. Software Development Plan (SDP)- describes a developer’s plans for conducting a software
development that involves a comprehensive gathering of all information required for the project.
2. Software Requirements Specifications (SRS) is a description of a software system to be develop, It lays
out functional and non- functional requirements.
3. Software Design Documents (SDD) - is a written description of a software product, that a software
designer writes in order to give a software development team overall guidance to architecture of the
software project.
4. Software Test Documents (STD) - it describes test planning, test design, test execution, test results
and conclusions drawn from the testing activity.
During the development of software, a multitude of document types will play a significant
role:
1. System Requirements software - these are prerequisites to use particular computer which
commonly includes:
1.1 Hardware Requirements
- Processing Power
- Memory
- Storage
- Display Adapter
- Peripherals
1.2 Software Requirements
- Operating System
- APIs and Drivers
- Web Browsers
1.3 Other Requirements
- Internet Connections
2. System Design – the process of defining the architecture, components, modules, interfaces of
particular software.
TYPES OF DESIGNS
1. Architectural Design- design of the system
2. Logical Design - represents data flows, inputs and output of the system
Ex. Entity – Relationship Diagram
3. Physical Design - relates to the actual input and output processes of the
system.
3 Sub–tasks of the Physical portion of a system design
- User Interface Design
- Data Design
- Process Design
3. System Architecture- it shows the structure and views of the functionality of the system.
Types of documentation include:
1. REQUIREMENTS
- Requirements Documentation is simply as requirements explains what software does and shall
be able to do.
- Statements that identify attributes capabilities, characteristics, or qualities of a system.
2. ARCHITECTURE/DESIGN
- Architecture documentation referred to as software architecture description.
- Overview of software.
3. TECHNICAL
- documentation of code, algorithms, interfaces, and APIs.
Product: System documentation
System documentation provides an overview of the system and helps engineers and stakeholders
understand the underlying technology. It usually consists of the requirements document, architecture
design, source code, validation docs, verification and testing info, and a maintenance or help guide. It’s
worth emphasizing that this list isn’t exhaustive. So, let’s have a look at the details of the main types.
However, there may be different types of software documentation, depending on the audience it is
created for. Here are some examples of the software documentation types:

Requirements documentation. Typically created in the beginning of a software development
project. Has the goal to clearly and precisely specify the expectations in regards to the software
being created. May include functional requirements, limitations, hardware or software requirements,
compatibility requirements, and so on.

Architecture documentation. Defines the high-level architecture of the software system being
created. May describe the main components of the system, their roles and functions, as well as the
data and control flow among those components.

Technical documentation - Documentation of the software code, algorithms, APIs. Written for the

technical audience like software developers.
End user documentation - Refer to User Guide.
As a rule, there’s a special team in a company occupied with technical writing - the documentation team.
Although, workflows can differ. In some companies, support, dev or QA can do documentation authoring.
Another option quite popular as far as software documentation is concerned is outsourcing. Many
organizations choose documentation writing to be done by outsource technical writers, and there are
some solid reasons for that.
Answer key:
TRUE - System architecture shows the structure and vies of the functionality of the system.
Preliminary exam ans:
These both explains how it operates or how to use it, and may mean different things to people In
different roles. (Product documentation)
These are detailed information for engineers about how to use every component of the product or
service as described by the developers or manufacturers. (Process documents)
These are referring to the documentation that describes how a product or services operates. (Process
documents)