26
| Date post: | 22-Dec-2015 |
| Category: |
Documents |
| View: | 218 times |
| Download: | 0 times |
My Background
• Technical Writer, Editor and Manager for 20 years• Worked for several software companies in
Seattle, including Microsoft and Boeing• Last position in Ames, Iowa, at the EDS
subsidiary, UGS PLM Solutions
Typical Software Development Organization
• Software Development• QA• Configuration Management• Product Management• Technical Documentation• Release Management• Usability Team
Typical Software Development Life Cycle Phases
ProductDefinition
High LevelDesign
DetailedDesign
Implementation Acceptance Support
•Customer Issues•Patch Support•Technical Support
•System testing (QA)•Beta Testing•Final Product Validation•Problem Evaluation•Problem Resolution
•Define form and function•Agree on “what” not “how”•Software Plan / Schedule
•Identify “how”•Define UI & architecture•Identify interfaces•Risk assessment•Scope & approach confirmation•Initial test planning
•Detail interfaces•Detail transactions•Identify testing approach•Define software / build approach
•Coding •Code Review•Unit testing•Product baseline established•Software testing
Documentation Processes mapped to SDLC
SDLC Phases
Product Definition High Level Design Detailed Design Implementation Acceptance Support
Assess Project
Research Project
Develop Design
Write Documentation
Submit for reviews and approval
Submit to Product Builds
Typical Deliverables
• Online Help• Release Notes• Installation Guide• Administrator’s Guide• Other: Customization Guide, Migration Guide• ReadMe (text file)
Documentation Process
Assess/Plan Project Assess whether new or updated documentation is
required Assess activities for the project and issues and risks Define Documentation team and schedule
Deliverables Documentation schedule Documentation Team
Documentation Process
Develop DesignDesign the Help system and other documentation that
will support the product release
To design your Help deliverables• Review feature and design description documents • Participate in project and feature review meetings • Create or update the Help topics for the new or
updated features, including decisions on the links to other topics, and adding graphics, if needed
• Update the Table of Contents, if needed with new topics and create new entries for the Index
• Create drafts of the Release Notes, Installation Guide, and other documentation needed
Documentation Process
Develop Design, contd.Deliverables
Initial draft work plan or Information Product Plan Drafts of Release Notes, Installation Guide and other
documentation
Documentation Process
Research ProjectGain a clear understanding of both the business and
functional aspects of the product/feature that is being documented
Review• Development’s Plan of Record (POR)• Functional and design specifications • Attend and actively participate in product
development and feature review meetings
Documentation Process
Research Project, contd.• Interview SMEs (developers) • Use the pre-release builds of the software • Check for new features and functionality in each
software build • Update and finalize the IPP (work plan)
Deliverables Final IPP
Documentation Process
Write documentationWrite the documentation for the project – the online Help
(HTML, typically) the Release Notes, the Installation Guide, and other deliverables, if applicable
To write your documentation• Focus on user needs • Write task-based documentation for the online Help • Use graphics to augment text and to help explain
concepts and procedures
Documentation Process
Write documentation, contd.• Use the iterative method to create documentation,
using up to three drafts• Submit for technical reviews • Update Release Notes, Installation Guide and other
documents
Deliverables Online Help Release Notes (second draft) Installation Guide (second draft) Other documentation (second drafts), if applicable
Documentation Process
Submit for reviews and approvalTo finalize the Help and other deliverables, use feedback
from the following reviews:
Technical review, performed by the developers provide a check on the accuracy of technical content
Documentation Process
Submit for reviews and approval, contd.
Editorial review, performed by the documentation team's technical editor provide a check for consistency in the following:
• Style • Grammar • Organization • Punctuation • Usability • Coherence • HTML code • Cross-browser compatibility • Consistency with other product documents in the
organization
Documentation Process
Submit for reviews and approval, contd.• QA review, performed by the QA, Usability, and
Customer Support groups provide a check for technical accuracy and consistency with the software
• Managerial review, performed by the documentation manager provide a final check for quality and completeness. The Manager signs off on the final version of the documentation
Deliverables Online Help (final) Installation Guide (final) Release Notes (next update) Other documentation (next updates)
Documentation ProcessSubmit for product builds
• Finalize the Table of Contents and Index• Create the start file and frameset for the online Help• Or, create the compressed Help file (.CHM)• Place files in source control program used by the
product
Deliverables• Online Help • Installation Guide • Release Notes• ReadMe (draft)• Other documentation (next updates)
Communication
• IPP (Example)• Status Reports (Example)• Tracking slips• Project schedule• Meetings – Development, Product
Management, Documentation Group, Weekly one-on-ones• Minutes of meetings and action items
Typical Tools
Commercially available tools• RoboHelp• HomeSite
Custom Tools and Design• XML• Modular documentation• Conditional Text
Certification
ISO and CMM
What is International Organization for Standardization (ISO)?
• ISO is a network of the national standards institutes of 148 countries• The source of ISO 9000, ISO 14000 and more than 14 000
International Standards for business, government and society• A network of national standards institutes from 148 countries working
in partnership with international organizations, governments, industry, business and consumer representatives. A bridge between public and private sectors.
• See http://www.iso.ch/iso/en/ISOOnline.frontpage for more information
What is International Standards Organization (ISO)?
ISO 9001:2000 is a set of requirements General Quality Management System Requirements Management Responsibility Requirements Resource Management Requirements Product Realization Requirements Measurement, Analysis & Improvement Requirements
ISO 9001:2000 has a specific focus Effective Processes Customer Requirements Training Effectiveness Communication Preventive Actions & Continual Improvement
Capability Maturity Model for Software
The Capability Maturity Model for Software (also known as the CMM and SW CMM) has been a model for judging the maturity of the software processes of an organization for many years now. This model helped organizations identify the key practices required to help them increase the maturity of these processes.
The CMM is organized into five maturity levels 1) Initial2) Repeatable3) Defined4) Managed5) OptimizingFor more information, see
http://www.sei.cmu.edu/cmm/cmm.html
Why certification?
• Certification is often required / desired by customers• Demonstrates that companies follow a standard set of
processes• Shows focus on management and improvement of the
business• Requires documentation and adherence to defined
processes Provides consistency in development effort Provides organization of processes Provides basis for future improvement
What you need to know to prepare for an audit
How you do your job What processes you follow Where your project work is stored
Know how to access the documented procedures, processes and support documents
How and to whom you report your statusBe able to explain the processes and use of support
documents Prepare to show evidence of how the processes &
support documents have been applied in doing your job
Show progress and improvement with metrics
