Creating an Installation Guide for a product on a Linux platform was an interesting experience for us. The project was challenging but knowledge-filled and fun to work on. During the project we learnt some key lessons that are required to develop a technical documentation (in MS Word) for a Linux based product.
What we learnt:

1. Linux commands are written at a SHELL and not a COMMAND PROMPT as for Windows® commands. Yes, we learned this the hard way when the SMEs commented on the fact.
2. Use the proper symbol depending upon the user. For example, if you are typing a command in the Shell, use the appropriate symbol when you type the command, depending on the type of user: root (admin) user and typical (non-admin) user.
# Use this symbol for admin users.
$ Use this symbol for non-admin users.
3. Check the capitalization, spacing, and spelling of all Linux commands. This is important as Linux commands are case sensitive.
4. Check the formatting styles for commands. For example:

  • Use Courier New font to represent a command.
  • Write the input commands and corresponding output on a light grey background.
  • Advisable to use a different colour (we used green) or bold Courier New Font for the output.

5. Authoring tools like MS Word auto-capitalize the first letter of a sentence. So, when you embed a Linux script in to any section of a Word document, the first letter in each line of the Linux script is automatically capitalized.

 
For example, when we wrote the following in the Installation Guide:
From the YaST Installing Packages screen (Figure 1), select the following packages:

  • apache2
  • perl-DBD-mysql
  • java-1_6_0-sun

The package names appeared as:

  • Apache2
  • Perl-DBD-mysql
  • Java-1_6_0-sun

Note: The first letter of the names of the names is now capitalized and no longer correct.
Getting these aspects straight was important and we realized that there was much to learn about how to represent Linux commands properly.

Author: Radhika Govindankutty