At my company I have seen a lot of bad software development practices over the years, so I have created a set of software development guidelines to help establish a set of best practices and baseline software requirements. I am publishing a series of experts from those guidelines here so that I might get some useful feedback that will help improve them.
All software must be documented. In addition to the specification documents outlined above, there normally should be at least two levels of documentation: the user level documentation and the administrator level or technical documentation. Some very small programs are so intuitive that user level documentation is not really required, but administrator level documentation should always be provided.
Since the service desk is the first point of contact for users with IT related issues and questions, documentation or a description of the location of documentation should be provided to the service desk. The service desk has the right to ask for additional documentation or clarification of existing documentation, and such documentation should be provided prior to the application’s deployment.
The documentation should be provided in an electronic format only.
The technical documentation should include the requirement specification, platform specification, a list of all system and core files that may be changed, and the configuration information. Installation instructions for all components should be provided where appropriate.
The user documentation should detail how to perform the various processes outlined in the requirement specification as well as the roles of users and limitations of each role or security level. Screenshots should be used for clarity.
Internationalization is the process of making a program portable between languages, regions, or cultures. Localization is the process of adapting a program for a given language, region, or culture. Since the Company is a global organization, all software should be internationalized, though it is not required that a program be localized.
The primary concern of internationalization in North America is the software’s language. However, if the software is to be used outside of North America then a wide range of internationalization concerns will arise. For example, if the software will be used in Europe then the developer must ensure that there are allowances for the difference in paper sizes, differences in currency, differences in the formatting of number representations, and many other issues.
Most good interpreted programming languages provide methods for using external language files, and these should be used whenever possible.
Remember that different human languages have different grammars, so assumptions should not be made on how sentences are formed. This is important when building strings from separate parts, for example.
Christopher
