Documentation Services

Transcription

1 Documentation Services Production Overview Arul Kumar Production Specialist

2 Agenda Team Structure Services and Responsibility Processes Support Tools and Technologies

3 Team Evelyn Sealander Senior Manager - Documentation esealand@novell.com Richard Ballard Production Specialist (Provo, USA) - 9:00 PM to 6:00 AM rballard@novell.com Arul Kumar Production Specialist (Bangalore, India)- 8:30 AM to5:30 PM karulkumar@novell.com

4 Documentation Services Mission Documentation Services is passionate about driving innovation into the documentation development process, improving documentation quality,, and providing optimal access to Novell documentation. For Novell, this means increased productivity, lower costs, and higher customer satisfaction.

5 Production Services SVN project work area setup Authoring tool support Autobuilds of in-process documentation Beta builds Public builds, simultaneous with FCS Localized documentation builds Post-release updates SVN repository management Retention and archive management Documentation tools testing and technical support ESD posting Legacy content transformation to DocSys format

6 Documentation Sites and URLs Build/HAIN Test/Staging Beta Live :30 - :45 build :00 sync :00 & :30 Sync :00 & :30 Sync Test/Staging = Beta = Live =

7 Bugzilla Work flow NEW CONFIRMED IN_PROGRESS Issues Yes REOPENED No RESOLVED VERIFIED

8 Using Bugzilla for Production Requests Bug classification (Product Line): Doc Tools Product: Doc Production Component: Product name (High Level and no version) OES ZENworks Novell Log Manager Etc. Severity & Priority Summary & Description Assign to, QA Contact & CC Deadline date

9 Bugzilla Request Information SVN/Perforce location of the Source material What deliverables (Guides, TOC, Readme, QS, Other) Which site is being updated (Staging, Beta or FCS) Update graphics Blind rev or date need to be updated Completion date Keep it as simple as possible Attachment details

10 Tools & Technologies FrameMaker SVN subversion DocSys Self-Service build system Broken link checker XML First workflow FTP tools Etc.

11 Tips & Tricks SVN Repository Best Practices Quick Starts are usually easier to read as a one HTML page unless they are long. The downside to a single HTML file is that it will break links if other guides in the product link to it. Readme & Release Notes should also be generated as a single HTML file. Single file HTML vs Single file HTML for novell.com. FrameMaker: Generate the TOC every time you update the book. This file is named toc.fm (lowercase) Etc.

12 Project Setup and SVN Best Practices Directory setup (new product or new version) How to handle an SP release.vs a new version release Consistent directory structure Naming convention Product name directory names book names graphic names profile names Commit at lowest level Do locks need to be in place Working in SVN browser instead of work area When updating TortoiseSVN client, it is best to have everything checked in.

13 Doc Handoff to Production Update all guides and generate XML and PDF (commit files). List URL where the guides should be placed. Let production know if there are updated graphics. You don't need to be specific, but list of the guides would be good. The date by which the build needs to be posted. If using profiles, indicate which one production should pull from. Indicate whether it is a blind rev or whether the dates need to be updated on the TOC.

14 Online Doc Review Checklist New/changed sections/doc pages TOC updated if needed (dates and links) PDF has been updated Test several different links (XRefExt and XrefProd) Check Left-nav links and Search link A-Z list on main doc page updated? If a new product or release, does it need the new icon?

15 Help Outputs Plain HTML (plainhtml) Help Single file and viewed in a browser Frame (helphtml) WebHelp Multiple files viewed in a browser. Has table of contents and search function MS HTML (winhtmlhelp) Help View the topics by launching the.chm file that is created Eclipse Help Not generated in Frame

16 Electronic Software Documents (ESD) ESD example ESD example with Eveluation code _button.html Be generic (ISO, URLs, etc.)

17