technical publication process
TRANSCRIPT
Novell® iFolder
Documentation Process
Radhika PC
Technical Writer
OPS Group
iFolder Doc Deliverables
© Novell Inc. All rights reserved3
Deliverables
Admin Guide
User Guide
Client Help – Windows and Linux
Security Admin Guide
Web Admin Help
Web Access Help
Readme
Pointer Readme
manpages
YaST help
ESD
iFolder Doc Process
© Novell Inc. All rights reserved5
Process Objective
To outline a process and a framework that enables
definition and implementation of a plan to meet all
product documentation and publishing requirements
© Novell Inc. All rights reserved6
DDLC
Doc Requirements Phase
Doc Planning
Doc Design
Development/Implementation Phase
Doc Testing Phase
Doc Release Phase
Post Release
© Novell Inc. All rights reserved7
Process
Tasks in PRD/functional spec for collecting Technical Publication
effort
Creation of the Table of Contents (minimum of three levels) to
show the organization of the document.
Review of the Table of Contents by the Team Lead(s).
Modifications to the Table of Contents, based on the review
comments.
Gathering inputs from engineers/other sources
Creation of the first draft of the document
Coordinating graphics creation and production
© Novell Inc. All rights reserved8
continues...
Review of the first draft by the developer(s) to check the
accuracy of the contents.
Incorporate technical review comments —- could be two or
more cycles
Peer review
Incorporates the peer review comments and sends the draft to
the Editor.
Incorporate language edit comments —- could be two cycles
Technical Publication testing
Final review and hand off
Testing the packaging/build for documentation integrity
Documentation Development Life Cycle-
Roles
© Novell Inc. All rights reserved10
Requirements
Role of the Development Team:
• Identify the need for documentation
• Discuss the documentation requirements with the Documentation team
• Determine documentation deliverables
• Identify resources for inputs
– Who provides the inputs?
– What are the input methods?
– Who reviews the docs?
Role of the Documentation Team:
• Study PRD, functional spec and determine doc requirement
© Novell Inc. All rights reserved11
Planning
Role of the Documentation Team:
• Estimate the documentation efforts for inputs and reviews for each
module/component
• Prepare documentation plan consisting of documentation effort,
deliverables, and schedule
• Share the documentation plan with stakeholders, and finalize the same.
Role of the Development and Test Teams:
• Review the documentation plan
• Integrate the documentation schedule with the product/engineering
schedule
© Novell Inc. All rights reserved12
Design
Role of the Documentation Team:
• Functional Specification review
• Re-validate Doc Plan
• Create and finalize the Table of Contents (TOC)
Role of the Development Team:
• Involve Technical Writers in design discussions
• Review the TOC
© Novell Inc. All rights reserved13
Implementation
Role of the Documentation Team:
• Author documentation deliverables
• Review the User Interface
Role of the Development Team:
• Provide timely documentation inputs
• Review the documentation deliverables
• Track the documentation schedule
© Novell Inc. All rights reserved14
Validation
Role of the Development Team:
• Technical accuracy and completeness
• Content organization
Role of the Test Team:
• Review doc, and test procedures
• Check help integration
• Verify doc completeness / readability
• Perform usability test of the documentation
• Reporting technical defects
Role of the Documentation Team:
• Incorporate valid comments
• Fix all documentation-specific bugs
© Novell Inc. All rights reserved15
Release
Role of the Project/Engineering Manager:
• Communicate well-in advance the Engineering build dates for doc / help
check-ins
Role of the Documentation Team:
• Convert the documentation deliverables in to the required format
• Submit documentation deliverables for production / localization
• Validate the build
© Novell Inc. All rights reserved16
Post-Release
Role of the Project/Engineering Manager:
• Conduct Postmortem review
Role of the Documentation Team:
• Archive documentation deliverables
• Address User Comments
• Participate in the Postmortem review
Stakeholders
© Novell Inc. All rights reserved18
Communication with Stakeholders
Weekly Cypress Doc Meeting with Provo
Fortnightly Meeting with Krish
iFolder Status Meeting
© Novell Inc. All rights reserved19
Useful Links
DPP Site
(https://et.innerweb.novell.com/project_pages/uxs/doc/reports/doc_deliverable_status_rpt.jsp?pid=12882)
Doc Localization Index Page
(https://et.innerweb.novell.com/project_pages/uxs/doc/reports/doc_loc.jsp?pid=10025)
Work group Wiki- Documentation
(http://nps-web.blr.novell.com:81/npswiki/index.php/Main_Page#Documentation)
Unpublished Work of Novell, Inc. All Rights Reserved.
This work is an unpublished work and contains confidential, proprietary, and trade secret information of Novell,
Inc. Access to this work is restricted to Novell employees who have a need to know to perform tasks within the
scope of their assignments. No part of this work may be practiced, performed, copied, distributed, revised,
modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of
Novell, Inc. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and
civil liability.
General Disclaimer
This document is not to be construed as a promise by any participating company to develop, deliver, or market a
product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in
making purchasing decisions. Novell, Inc. makes no representations or warranties with respect to the contents
of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any
particular purpose. The development, release, and timing of features or functionality described for Novell
products remains at the sole discretion of Novell. Further, Novell, Inc. reserves the right to revise this document
and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions
or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell,
Inc. in the United States and other countries. All third-party trademarks are the property of their respective
owners.
© Novell Inc. All rights reserved22
Color Palette
RGB
224 0 0
RED
RGB
230 120 20
ORANGE
RGB
98 158 31
GREEN
RGB
0 166 238
BLUE
RGB
60 60 65RGB
90 90 100
RGB
204 204 205
DK GRAY
Note:The gray dotted-line box represents the margins or
“working area” into which all text and most graphics
and diagrams should conform.
How to Add Novell Colors to Your
OpenOffice Color Palette:1. Go to the “Tools” menu
2. Select “Options”
3. Expand “OpenOffice.org”
4. Select “Colors”
5. Delete existing colors (one-by-one)
6. Add Novell Colors by giving them a name and entering
RGB values
7. Click “OK”RGB
50 118 109
TEAL
RGB
255 221 0
YELLOW
MD GRAY LT GRAY
© Novell Inc. All rights reserved23
Graphics & Typeface
RED
ORANGE
GREEN
BLUE
GRAY
Icons/Lines: This presentation refresh simplifies the current template and pushes focus on the content being presented. The icon library will continue to be utilized, but a refresh will be noticeable with the addition of the “Bubble” set of icons, and a subtle color shift. These icons are created to provide a professional, consistent look. When these icons are used sparingly, and in direct relation to the content on the slides, our presentations will communicate and work more effectively.
Note:
Typeface: Arial has been selected as the new typeface for all Novell communications. The following were considered.
1. Our typeface needs to be designed to carry information quickly to the reader.
2. It needs to be usable for Novell employees in company correspondence and presentations, as well as for outside vendors for marketing and promotion.
3. It needs to easily function on the Linux, Windows and Macintosh platforms.
4. And finally, Arial was created for these exact purposes.
Download Icon Library at: http://innerweb.novell.com/brandguide
How to Add Novell Icons to OpenOffice Gallery:1. Go to the “Tools” menu
2. Select “Gallery”
3. In the Gallery window select “New Theme...”
4. With the “General” tab active name your new theme (ie.Red flat)
5. Select the “Files” tab.
6. Select “Find Files...”
7. Find the downloaded folder containing the icons named and click “Select”
8. Select “Add All” and then “OK”
9. Repeat for all icon groups
RED
ORANGE
GREEN
BLUE
GRAY
Bub
ble
Flat 3-D