Hyderabad Technical WriterA blog for Technical Writing Tips and Tricks, Quick Reference Guides, Technology, Hyderabad, and India
About Readme
Readme files contain useful information about the product and are created during an application installation. The readme contains last minute important product information that is not available in the program guides or online help systems. Sometimes, it contains information pertinent to your specific configuration.
Packaging Readme
A readme file provides information about other files like: Implementation guide and Release Summary in a directory and is very commonly distributed with computer software. The readme file is always an ASCII text file, titled “README.TXT”. But based on client requirements, this file is also made available in other formats such as: an html file, .utf8, or Microsoft Word file.
Process of Generating Readmes
Readmes are created and updated based on the inputs provided by the development, QA, and Technical Support teams. And, the Technical Writer or the Technical Publications is responsible for formatting in the tool or a template, which is approved by an organization.
It might be tricky at times when you have to decide whether or not to include certain information in readme that are not to standard, it is the job of the Technical Writer or Technical Publications to point that out and get the issue resolved, either by making sure Development agrees that the information should go in some other appropriate deliverable, or by discussing with the appropriate parties (development, QA, and Technical Support teams and so on) whether we can deviate from standard. If the decision is to move the information to another deliverable, it is essential that you must update the appropriate deliverable accordingly.
Once the Technical Writer or Technical Publications updates the readme document with relevant information under various sections as mentioned in the previous paragraph, it is essential that this deliverable is sent for reviews. So, that the deliverable is complete, accurate, error free. In order to achieve this, the Technical Writer or Technical Publications should send the document for technical review for technical accuracy and copy edit for consistency in word usage, style, spelling, grammar, punctuation, layout and formatting issues.
Readme Contents
The contents of a readme vary, usually featuring operating instructions, and often a list of the names and purposes of files one should expect to be there or information about the maker of the files.
A typical readme file contains the following sections and topics:
- Welcome Note
- Operating System Support
- System Requirements
- Installation Considerations
- General Considerations
- Known Issues
- Published Fixes
- Critical Bug Fixes
- International Support
- Documentation and
- Technical Support Contact Details
Uses of Readme (or appropriate)
- Readme is usually the first documents reviewed by a user, and hence includes important information about the product. It also provides information about other documentation available with the product.
- Readme contains simple steps and answers about the new release of a product.
- Readme provides tips and tricks for known issues and problems.
- Readme contains updated information about each new version of a product.
- Contains Technical Support team details for technical assistance.
