Writing Technical Documentation

[tntcoder]

Hi,

I need to write some technical documentation for the software part of my comp sci dissertation. Could someone explain to me what this should include as im a bit lost and have heard varied opinions.

Am I correct in thinking it should include:
- Class Diagrams / Other evil UML designs
- Detailed descriptions of 'every single' object/function/method in the source code, covering how they work, interrelate and what their purpose in the system is

Is that along the right lines? anything else I should cover?

Thanks for any help,

Jack

 

[RobH]

- Detailed descriptions of 'every single' object/function/method in the source code, covering how they work, interrelate and what their purpose in the system is

I don't think you should go into excessive low level detail, rather a more high level overview of the code, mentioning any noteworthy aspects and algorithms.

For my dissertation, the general structure of the report is as follows:

-Introduction
-Context
-Requirements Analysis
-Design
-Implementaiton
-Testing (May come under Evaluation)
-Evaluation
-Conclusion
-References & Appendix

 

[Django x2]

It depends what you're writing about tbh.

One of the best methods is to produce a high level design then follow this up with a detailed design document.

It should list things like dependencis, assumptions, theory, UMLs, applications / software used, research, design, implementation, testing, evaluation, conclusion maybe a sub section on future development (what would be done if you had more time) then the usual appendix adn references.

 

[tntcoder]

Ok thanks guys, so are you saying rather than having a special technical doc as an appendix item, it should be broken down and covered in the appropriate sections throughout the main report?

 

[Django x2]

In corporate guise you'd do high level design doc then detailed design doc once the first had been signed off. This is not really viable for a diss, so lay it out in a format similar to what RobH has said but whack all your code in to the Appendix but make sure its referenced in your design section.

 

[tntcoder]

Ok thanks very much