TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:RE: Online or print for SDK material? From:Matthew Horn <mhorn -at- macromedia -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 31 Dec 2002 11:02:19 -0500
+1 one providing printable manuals as opposed to only online help for SDKs. I may be in the minority, but as both a writer and programmer, I prefer to have a book BESIDE me while I code in FRONT of me. Sure, I could attach a second monitor to get more screen real-estate or constantly hit Alt-Tab to switch between the application and the SDK documentation, but I prefer not to do either.
Cutting and pasting of code samples is overrated. I will have to adapt the code samples to fit my particular application anyway. Usually I just need to see an illustration of a method's use anyway, and not have to copy everything.
If you provide both a printable and online reference help, you should change the structure of the help to fit the medium. For the online reference, I like a Javadocs-like interface with tons of x-refs to related classes, objects, methods, interfaces etc. This is best done with an automated tool.
For the PDF, each chapter should address a particular topic and then using examples of the APIs that are related. Make the PDF more of a conceptual grouping and the online help more of a hierarchical grouping.
Matthew Horn
Sr. Technical Writer
< m a c r o m e d i a >
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!
Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
