Editing

What is editing?

Editing is improving the quality of the content produced by an author or individual by adhering to the following:

• Clear
• Consice
• Correct
• Complete
• Consistent

Why is editing required?

Writers are humans and can miss the "obvious" spellings and other rules. The editors may detect the missed errors, thus ensuring conformance to the standards.

Writers, peers or designated editors can edit the content of a document.

The aspects of editing

The following aspects can be considered:

1. Language - which includes spelling, grammar, punctuation, parallelism and symbols, word usage and terminology
2. Organization - Trademark acknowledgements, legal and safety statements, regulations, standards and style guidelines and integrity (title, headers and footers)
3. Reader - Safety and usability, readability and navigation, structure of information, and ambuguity
4. Author - Respect for the content and schedule (to avoid last minute updates), sensitivity in providing the comments

Documentation Development Life Cycle

Documentation Development Life Cycle aka DDLC describes the cycle from the pre-engagement meeting with a client until the document delivery.

Just like every software product is developed adhering to the Software Development Life Cycle (SDLC),

The stages in DDLC are:

1. Analysis
2. Design
3. Develop
4. Evaluate
5. Deliver

Analysis

In this phase, the documentation needs, tools required, resources etc. are analyzed. The project plan is submitted to the client for review and approval.

Deliverables

• Project plan
• Progress report

Design

In this stage, the requirements from stage 1 (Analysis) are established. A detailed outline is developed. An estimate is made on the total number of pages in the document. Template and prototype are also developed in this stage. When all the above are set in place, revise and review the project plan.

Deliverables

• Detailed outline
• Project plan revisions
• Progress reports

Development

In this stage, the number of hours required to develop the document is defined. The prototype is approved by the client. If there are any graphics, design or develop them. Drafts are sent for review. Finally, revise and edit drafts and obtain client approval for all the documents developed at this stage.

Deliverables

• Prototype
• Style guide
• Drafts
• Progress reports

Evaluation

In this stage, appendices, glossary, etc. are created and a final edit is performed. Document is sent for final approval and the ToC's are created. Finally, client approval and sign-off is obtained.

Deliverables

• Final drafts with graphics
• Progress reports

Delivery/Release

The documents are released to the customer in appropriate format. The maintenance or updates (version updates) required is determined in this stage.

Deliverables

• Document

Version control

What is version control?

Version control aka revision control or source control is an aspect of software and documentation configuration management; it is the change management to documents, programs, large web sites and other information stored as computer files. It is most commonly used in software development, where a team of people may change the same files. Changes are usually identified by a number or letter code, termed the revision number, or revision level. Version control is a software to keep track of all the revisions and releases pertaining to a product.

For instance, an initial set of files is revision 1. When the first change is made, the resulting set is revision 1.1 or 2, and so on.

Each revision is associated with a timestamp and the name of the person making the change.

There are many configuration systems available in the market today. Listed below are some of the advantages of having a document CMS.

Advantages of having a documentation configuration management system

• Tracking of all revisions and releases of project’s files can be easily managed
• Archive of changes is well maintained
• Any level of previous changes can be retrieved
• Collabarative – ie allows to make concurrent changes to a file

Process

In general, process can be defined as a sequence of interdependent and/or dependent procedures, which at every stage, consume one or more resources (employee, time, money, etc.) to convert input into output. These output can be served as input to the next stage until the goals are achieved.

In simpler terms, process is a series of actions, changes or functions that bring about a known result or goal.

The process established in each company varies, depending on the requirements and available resources. But, in general the technical publications has a process set up, which must be adhered to by the team. The process overview diagram is shown below.

Technical Writing

Technical Writing: Types of technical documents

 

In engineering,technical documentation refers to any kind of document that describes the functionality and architecture of any product under development or testing. Types of documentation include the following:

• User manuals
• Release notes
• Application note
• Data sheets
• Online help
• Troubleshooting manuals
• Feature Activation Guides

User manuals

User manuals, commonly known as user guides are manuals that explain in detail about a particular product or a system. These manuals are written by a writer and are commonly associated with images which include screen shots, clear or simplified images.

Contents of a User manual

The sections in a user manual or guide commonly include the following:

1. Cover page - title and copyright
2. Preface - which contains details of reference documents and information on how to navigate the guide
3. Contents page
4. Product overview - which gives details about the product
5. Troubleshooting section detailing possible errors that may occur, along with the problem solving steps on how to resolve the errors
6. FAQ's
7. Glossary

Release notes

Release notes are documents that are distributed along with the product that is either in the development or testing phase. For products that are already in use by the clients, the release notes is a supplementary document that is delivered to the customer when there is a bug fix or an enhancement in the current release.

Contents of release notes

The sections in a release notes commonly include the following:

1. Cover page - title and copyright
2. Preface
3. Contents page
4. Overview - which includes the following:
• Purpose
• Audience
• Scope
• Assumptions
5. System requirements - which includes the following:
• Hardware
• Software
• Patch baseline
6. Fixed bugs
7. Known bugs
8. Limitations and Enhancements

For most companies, release notes are written by the development teams. It is not easy for a technical writer to do this, for the fact that the writer should know the product very well and also be involved in the testing phase (having access to the bug reporting tool), know the packages to be delivered and additional useful information to be mentioned in the release. These information are gathered during end-to-end product implementation. When the writer is involved in the process of software release management,it becomes easier to create a release document.

Application note

An application note is a document that gives specific details on using a component in an application; for instance, the physical assembly of a product containing the component. Application notes are either appended to a data sheet or are released as a stand-alone document.

Data sheets

A data sheet summarizes the performance and other technical characteristics of a product, component (usually electronic in nature) or a software in sufficient detail to be used by a design engineer to integrate the component into a system.

Online help

Online help is a procedural, topic-oriented information that is delivered through a software. Most online help is designed to assist the user in the use of a software application or OS, but it can also be used to present information on a broad range of subjects.

Troubleshooting manuals

Troubleshooting is a form of problem-solving that is applied to something that has suddenly stopped working since its previous working state. It requires identification of the malfunction(s) or symptoms within a system. Then, experience is commonly used to generate possible causes of the symptoms. Determining which cause is most likely is often a process of elimination - eliminating potential causes of a problem.

Finally, troubleshooting requires confirmation that the solution restores the product or process to its working state.

The steps involved in this process are collectively put into the document. Such a document is called a troubleshooting manual.

Feature Activation Guides

A feature activation guide, is a document that defines the new feature introduced in the release and also details the procedure or process involved in activating that feature.

This may require the writer to have access and exposure to some of the test environment/network.

What is technical writing?

Technical writing is probably the most widely read form of written communication around, with the exception of advertising. It is a craft that aims to provide technical, business or educational information in a clear and concise manner. 


Technical writing in business can include training manuals, employee guidelines or handbooks and other specialized writing that is task specific.


Technical writing is arguably more difficult than other forms of writing because of the fact that it must be clear and to the point. Good technical writing should not leave any room for imagination and it must anticipate and answer any questions or problems that may arise. This aspect of technical writing is often seen in ‘frequently asked questions’ and ‘trouble shooting’.


The demand for technical writers is high, which makes a career in technical writing a great option for many writers or others who have great organizational, grammar and communication skills. Technical writing provides a decent salary and is often available to freelancers as well as onsite employees. There are many training programs available for people who wish to enter the field of technical writing.

Hi!!!

This is my third blog - and the first one related to writing! I will post articles I have read and learnt during my experience here, whenever I get time!

Happy reading it!