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!