how to write Project Documentation ? answer added - Printable Version +- Free Academic Seminars And Projects Reports (https://easyreport.in) +-- Forum: Project Ideas And Disscussion (https://easyreport.in/forumdisplay.php?fid=32) +--- Forum: Engineering Project Ideas (https://easyreport.in/forumdisplay.php?fid=33) +---- Forum: Project Request (https://easyreport.in/forumdisplay.php?fid=46) +---- Thread: how to write Project Documentation ? answer added (/showthread.php?tid=26701) |
how to write Project Documentation ? answer added - sreeraju - 08-16-2017 Project Documentation Project documentation is used to define the way in which a project will be managed and the governance surrounding it. Project reports cover all the aspects of business, from analyzing the market, confirming availability of various necessities such as plant & machinery, raw materials to forecasting the financial requirements. The scope of the report includes assessing market potential, negotiating with collaborators, investment decision making, corporate diversification planning etc. in a very planned manner by formulating detailed manufacturing techniques and forecasting financial aspects by estimating the cost of raw material, formulating the cash flow statement, projecting the balance sheet etc. Software Documentation What is a Software Product? A software product is represented and distributed as a package of documentation Includes many kinds of documentation Often organized as a directory of subdirectories Some documentation is expressed in formal language Meant to be read by machines or other software Can be very hard or impossible for humans to read Other documentation is express in natural language Can be very hard for humans to understand The use of logic and mathematics can significantly improve the quality of documentation But can still be very hard for humans to understand Purpose of Software Documentation 1. Provide a software product in an executable form 2. Describe the software product The requirements the product is intended to satisfy The design of the product The implementation of the product The capabilities and limitations of the product The product from different perspectives 3. Show that the product is correct 4. Make the product easier to: Use Maintain Reuse Kinds of Software Documentation 1. Requirements specifications 2. Design descriptions 3. Source code 4. Verification and testing results 5. Instructions for the administrator 6. Instructions for the user 7. Standards documentation What makes Software Documentation Different? 1. Software is not physical or strongly visible 2. A software product is represented and distributed as documentation 3. Software involves formal, machine-readable languages 4. The content of software is largely logic and mathematics 5. Software documentation has many different purposes 6. A software product needs many kinds of documentation Styles of Software Documentation 1. Tutorial Teaches some aspect of the software Often used for user documentation 2. Reference document Software parts are presented individually Is not intended to be read cover to cover 3. Hyperlinked set of documents Requirements are connected to the design, the design is connected to the code, etc. 4. Layered set of documents Presents software at different layers of abstraction Example: algorithms are presented separately from code 5. Derivational document Shows how software is derived from the requirements May be a proof of correctness 6. Single-source document Different documents and different views are generated from a single source Example: literate programming where a documentation file and a code file are generated from the same source Example: Javadoc and similar approaches Example: A family of manuals generated from the same source 7. On-line, searchable documentation Can include a cut-and-paste facility for assembling new documentation 8. Documents with reader-controlled syntax Reader chooses his or her own presentation syntax, conventions, and format Frees the reader from the standard syntax of a formal language Code: General Recommendations Structure the code in a consistent manner As a general rule, choose clarity before efficiency Express the structure of the software s design in the software s code Follow the conventions of the programming language being used Keep the Code Simple Write procedures that fit on one screen Put at most one programming statement on a line Keep the following measures low: Loop nesting level Conditional nesting level Number of local variables in a procedure Avoid control structures that radically change state Exits, gotos, state jumps, self-modifying code Avoid nonstandard language features Naming Programming Entities Naming is an important but difficult task One should employ a naming convention Names should be short and descriptive The more global the entity, the more descriptive the name should be The more local, the shorter the name can be A name may include: Type of entity or return value Name of module Words in a name can be separated by underscores, hyphens, and case changes, but avoid using spaces Formatting Code Use formatting to display the structure of the code Indentation to display subordinate relationships between code Alignment to identify blocks of code Blank lines to separate blocks of code Write fully bracketed code to facilitate maintenance Write code in tabular form whenever possible Avoid wrap-around code Line up comments to the right of the code Scope of Variables Make the scope of variables as narrow as possible Avoid global variables A wide-scoped variable is: Harder to maintain because its instances may appear far apart from each other More easily corrupted because its data can be modified by diverse procedures Decrease the scope of a variable by introducing procedures for accessing the variable Procedures Use a convention for naming and ordering parameters Make explicit and carefully control any side-effects Keep the use of side-effects to a minimum Make the scope of procedures as narrow as possible Any code fragment used more than once should be made into a procedure Make procedures powerful Use simple procedures to invoke powerful procedures in special ways Commenting Code Begin every code file with: Copyright statement Authors Description of contents Revision date and log of changes made to the file Comment: Each variable declaration Each procedure definition Loops and larger blocks of code Anything that is not obvious Avoid excessive comments in procedure bodies Write code so that what it does is obvious |