1 / 10

Software Documentation

Software Documentation. David Geldreich (DREAM). Tools. Software Documentation. Requirements. Global architecture. UML. Local architecture. Implementation. Editor. Compilation. Compiler. Linker. Build. Link. IDE. Tests. Debug. Debugger. Profiling. Profiler. Install.

daire
Download Presentation

Software Documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Software Documentation David Geldreich (DREAM)

  2. Tools Software Documentation Requirements Globalarchitecture UML Localarchitecture Implementation Editor Compilation Compiler Linker Build Link IDE Tests Debug Debugger Profiling Profiler Install Distribution Time

  3. Outline • What ? • Why ? • Who ? • When ? • How ? • Where ?

  4. What ? Various types of documentation • Specification/Planning • Architecture/Design • Overview of software • Includes relations to an environment and construction principles to be used in the design of software components • Technical • Documentation of code, algorithms, interfaces, and APIs • End User • Manuals for the end-user, system administrators, and support staff • Marketing/Commercial • Product briefs and promotional materials

  5. Why ? • Documentation isn't the primary issue, communication is • Define the target audience of the documentation • Comprehensive documentation does not ensure project success • Development planning : • Time spent documenting is time not spent writing code • Different needs during and after the development

  6. Who ? When ? • Who ? • Everybody must document his code • Nobody will do it for you • Comments and a reference manual have different goals • When ? • Document just-in-time : when you need it • Document something only when it has stabilized • Out of sync documentation is almost useless • Benefit of having documentation must be greater than the cost of creating and maintaining it

  7. How ? Where ? • Text editors : emacs, Latex, Word, … • Specific tools : • Planning : MS Project, … • Spec, Architecture/Design : UML Tools (MagicDraw, dia, …), … • Technical : document extractor (doxygen, javadoc, …), … • Marketing : Illustrator, Dreamweaver, … • Must be versioned with the rest of the software

  8. Demonstration • Ogre3D : http://www.ogre3d.org/ • Wiki : http://www.ogre3d.org/wiki/index.php/Main_Page • User Manual : http://www.ogre3d.org/docs/manual/ • API Reference built with doxygen : http://www.ogre3d.org/docs/api/html/ • http://www.ogre3d.org/docs/api/html/classOgre_1_1Frustum.html • http://ogre.cvs.sourceforge.net/ogre/ogrenew/OgreMain/include/OgreFrustum.h?revision=1.30&view=markup

  9. Conclusion • What ? Various types of documentation • Why ? Define the audience of the documentation • Who ? Everybody • When ? Document something when it has stabilized • How ? Text editors and specific tools • Where ? Close to the code and versioned

  10. Useful Links • Recommendations for software development at INRIA : • http://devel.inria.fr/recom/ • Software documentation : • Agile Documentation : http://www.agilemodeling.com/essays/agileDocumentation.htm • Agile Documentation Strategies : http://www.ddj.com/dept/architect/197003363?pgno=2 • Wikipedia : http://en.wikipedia.org/wiki/Software_documentation • Tools : • Mail-list, wiki, web : http://gforge.inria.fr • UML : http://en.wikipedia.org/wiki/Unified_Modeling_Language • Javadoc : http://java.sun.com/j2se/javadoc/ • Doxygen : http://www.doxygen.org/ • List of development software at INRIA Sophia • http://www-sop.inria.fr/dream/logiciels.html

More Related