Software Documentation Written By: Ian Sommerville Presentation By: Stephen Lopez-Couto.

Slides:



Advertisements
Similar presentations
Configuration management
Advertisements

Software change management
Configuration management
Software Quality Assurance Plan
Business Development Suit Presented by Thomas Mathews.
System Development Life Cycle (SDLC)
Sixth Hour Lecture 10:30 – 11:20 am, September 9 Framework for a Software Management Process – Artifacts of the Process (Part II, Chapter 6 of Royce’ book)
July 11 th, 2005 Software Engineering with Reusable Components RiSE’s Seminars Sametinger’s book :: Chapters 16, 17 and 18 Fred Durão.
IMS Systems Analysis and Design Communication and Documentation: Additional Notes on Written Reports.
Technical Writing II Acknowledgement: –This lecture notes are based on many on-line documents. –I would like to thank these authors who make the documents.
CSE Information Systems 1 Communication and Documentation: Additional Notes on Written Reports.
©2003 Prentice Hall Business Publishing, Accounting Information Systems, 9/e, Romney/Steinbart 18-1 Accounting Information Systems 9 th Edition Marshall.
Examine Quality Assurance/Quality Control Documentation
©Ian Sommerville 2000 Software Engineering, 6th edition. Chapter 5 Slide 1 Requirements engineering l The process of establishing the services that the.
©Ian Sommerville 2004Software Engineering, 7th edition. Chapter 17 Slide 1 Rapid software development.
Software Configuration Management
Configuration Management Avoiding Costly Confusion mostly stolen from Chapter 27 of Pressman.
System Implementation
Documentation 1. User Documentation 2. Technical Documentation 3. Program Documentation.
Basics of Good Documentation Document Control Systems
XML, DITA and Content Repurposing By France Baril.
This chapter is extracted from Sommerville’s slides. Text book chapter
Project Proposal: Academic Job Market and Application Tracker Website Project designed by: Cengiz Gunay Client: Cengiz Gunay Audience: PhD candidates and.
Section 2.1 Compare the Internet and the Web Identify Web browser components Compare Web sites and Web pages Describe types of Web sites Section 2.2 Identify.
Introduction to Information System Development.
Oracle iLearning/Tutor Integration Jan  Oracle iLearning Overview  Oracle Tutor Overview  Benefits of integration  Manual integration process.
S/W Project Management
Database Systems COMSATS INSTITUTE OF INFORMATION TECHNOLOGY, VEHARI.
Article: Source Code Review Systems Author: Jason Remillard Presenter: Joe Borosky Class: Principles and Applications of Software Design Date: 11/2/2005.
1 Web Basics Section 1.1 Compare the Internet and the Web Compare Web sites and Web pages Identify Web browser components Describe types of Web sites Section.
MEASUREMENT PLAN SOFTWARE MEASUREMENT & ANALYSIS Team Assignment 15
Planning and Writing Your Documents Chapter 6. Start of the Project Start the project by knowing the software you will write about, but you should try.
Document Control Basics of Good Documentation and
 To explain the importance of software configuration management (CM)  To describe key CM activities namely CM planning, change management, version management.
Software Requirements Engineering CSE 305 Lecture-2.
Architecture for a Database System
Configuration Management (CM)
©Ian Sommerville 2004Software Engineering, 7th edition. Chapter 29 Slide 1 Configuration management.
Creator: ACSession No: 16 Slide No: 1Reviewer: SS CSE300Advanced Software EngineeringFebruary 2006 (Software Quality) Configuration Management CSE300 Advanced.
1.  Describe an overall framework for project integration management ◦ RelatIion to the other project management knowledge areas and the project life.
UNIT 14 1 Websites. Introduction 2 A website is a set of related webpages stored on a web server. Webmaster: is a person who sets up and maintains a.
© 2001 Business & Information Systems 2/e1 Chapter 8 Personal Productivity and Problem Solving.
Lead Black Slide Powered by DeSiaMore1. 2 Chapter 8 Personal Productivity and Problem Solving.
© Copyright 2011 John Wiley & Sons, Inc.
DITA Single Source technology. What is Single Source? Single source technology is a concept of publishing documents when same content can be used in different.
1 Technical & Business Writing (ENG-315) Muhammad Bilal Bashir UIIT, Rawalpindi.
IFS310: Module 7 Business Requirements Statement Interpersonal Skills and Communications.
Metadata By N.Gopinath AP/CSE Metadata and it’s role in the lifecycle. The collection, maintenance, and deployment of metadata Metadata and tool integration.
1 CS 501 Spring 2003 CS 501: Software Engineering Lecture 26 Delivering the System.
Lesson 3-Multimedia Skills. Overview Members of a multimedia team. Roles and responsibilities in a multimedia team.
1 Chapter 12 Configuration management This chapter is extracted from Sommerville’s slides. Text book chapter 29 1.
Chapter 1 © 2013 Pearson Education, Inc. Publishing as Prentice Hall Chapter 1: The Database Environment and Development Process Modern Database Management.
Oman College of Management and Technology Course – MM Topic 7 Production and Distribution of Multimedia Titles CS/MIS Department.
~ pertemuan 4 ~ Oleh: Ir. Abdul Hayat, MTI 20-Mar-2009 [Abdul Hayat, [4]Project Integration Management, Semester Genap 2008/2009] 1 PROJECT INTEGRATION.
Process of Creating a Website By: Ryan Millevoi and Lauren Gallo.
OpenPegasus Documentation Discussion What should we change, what should we keep? KS OpenPegasus Developers Conference 27 September 2012.
11 Proposals and Formal Reports. Introduction Proposals o Informal o Formal Research Writing Formal Reports Elements of Formal Reports.
Abstract  An abstract is a concise summary of a larger project (a thesis, research report, performance, service project, etc.) that concisely describes.
Chapter 25 – Configuration Management 1Chapter 25 Configuration management.
Working in Groups in Canvas
Chapter 11: Software Configuration Management
Software Documentation
Chapter 4 Systems Planning and Selection
Roberta Roth, Alan Dennis, and Barbara Haley Wixom
Chapter 10 Development of Multimedia Project
Project Management Process Groups
Chapter 11: Software Configuration Management
Chapter # 5 Supporting Quality Devices
Requirements Document
Geant4 Documentation Geant4 Workshop 4 October 2002 Dennis Wright
Presentation transcript:

Software Documentation Written By: Ian Sommerville Presentation By: Stephen Lopez-Couto

Discussion Topics 1. Introduction 2. Documentation Requirements 3. Process and Product Documentation 4. Document Quality 5. Standards 6. Document Preparation 7. Document Storage 8. Conclusion

Introduction This paper provides an overview of the Reasons for software documentation Types of software documentation Ways to implement software documentation Processes and “Good Ideas”

Documentation Requirements General requirements of all software documentation Should provide for communication among team members Should act as an information repository to be used by maintenance engineers Should provide enough information to management to allow them to perform all program management related activities Should describe to users how to operate and administer the system

Documentation Requirements In all software projects some amount of documentation should be created prior to any code being written Design docs, etc. Documentation should continue after the code has been completed User’s manuals, etc. The two main types of documentation created are Process and Product documents

Process Documentation Used to record and track the development process Planning documentation Cost, Schedule, Funding tracking Schedules Standards Etc. This documentation is created to allow for successful management of a software product

Process Documentation Has a relatively short lifespan Only important to internal development process Except in cases where the customer requires a view into this data Some items, such as papers that describe design decisions should be extracted and moved into the product documentation category when they become implemented

Product Documentation Describes the delivered product Must evolve with the development of the software product Two main categories: System Documentation User Documentation

Product Documentation System Documentation Describes how the system works, but not how to operate it Examples: Requirements Spec Architectural Design Detailed Design Commented Source Code Including output such as JavaDoc Test Plans Including test cases V&V plan and results List of Known Bugs

Product Documentation User Documentation has two main types End User System Administrator In some cases these are the same people The target audience must be well understood!

Product Documentation There are five important areas that should be documented for a formal release of a software application These do not necessarily each have to have their own document, but the topics should be covered thoroughly 1. Functional Description of the Software 2. Installation Instructions 3. Introductory Manual 4. Reference Manual 5. System Administrator’s Guide

Document Quality Providing thorough and professional documentation is important for any size product development team The problem is that many software professionals lack the writing skills to create professional level documents

Document Structure All documents for a given product should have a similar structure A good reason for product standards The IEEE Standard for User Documentation lists such a structure It is a superset of what most documents need The authors “best practices” are: 1. Put a cover page on all documents 2. Divide documents into chapters with sections and subsections 3. Add an index if there is lots of reference information 4. Add a glossary to define ambiguous terms

Standards Standards play an important role in the development, maintenance and usefulness of documentation Standards can act as a basis for quality documentation But are not good enough on their own Usually define high level content and organization There are three types of documentation standards ->

1.Process Standards Define the approach that is to be used when creating the documentation Don’t actually define any of the content of the documents Draft ReviseCheck Peer Reviews

2. Product Standards Goal is to have all documents created for a specific product attain a consistent structure and appearance Can be based on organizational or contractually required standards Four main types: 1. Documentation Identification Standards 2. Document Structure Standards 3. Document Presentation Standards 4. Document Update Standards

2. Product Standards One caveat: Documentation that will be viewed by end users should be created in a way that is best consumed and is most attractive to them Internal development documentation generally does not meet this need

3. Interchange Standards Deals with the creation of documents in a format that allows others to effectively use PDF may be good for end users who don’t need to edit Word may be good for text editing Specialized CASE tools need to be considered This is usually not a problem within a single organization, but when sharing data between organizations it can occur This same problem is faced all the time during software integration

Other Standards IEEE Has a published standard for user documentation Provides a structure and superset of content areas Many organizations probably won’t create documents that completely match the standard Writing Style Ten “best practices” when writing are provided Author proposes that group edits of important documents should occur in a similar fashion to software walkthroughs

Online Documentation Either internal to the application or Web based Requires rethinking the presentation style since normal “paper” documentation approaches do not carry over well Should act as a supplement to paper documentation Biggest benefit of Web docs are that they are always current

Document Preparation Covers the entire process of creating and formatting a document for publication Author recommends using specialized (and separate) tools for creating and preparing documents This is only important for user documentation It is often important to have a professional writer or document publisher evaluate documents before publication to ensure they look good and will carry over to paper well

Document Storage Author Recommends (in 2001) File System to store the actual documents Database to store references to the files with metadata to allow searching and referencing Today it is probably better to use a content management systems CVS or Subversion Free and Open Source Easy to setup and maintain

Conclusion Good overview of documentation Though most documentation “requirements” are based on contract requirements Hard to cover things like that in a paper like this Most of the content seemed to be referring to user documentation Design and other similar docs (often times more graphical than textual) were overlooked

Questions? or I will be here next class