TECHNICAL WRITING THERE ARE SIX WRITING SAMPLES ON THIS PAGE. Click to learn how I can cross-link my technical writing with your Support, Development, and Marketing teams, creating an integrated multi-node information matrix, providing a unique and powerful enhancement to your operations. | ||
WRITING SAMPLE #1 Help File for "Marionette" Software Program Marionette is a control program for selecting and controlling remote video projectors used in education; the program is a product of Crestron Electronics. I wrote the entire help system. The file was too large to easily reproduce here, but is a relatively quick download (Windows .zip file, about 12KB, 01 second at 56k). After download, to display the Help file properly, be sure to extract the files by right clicking the .zip file and selecting "Extract All" (do not merely double-click the .zipped folder, and do not select "Open With" or "Send To"). I later added screen captures to this help file, such at that, below, but they are not present in the downloadable sample file. Here is a small example of an interface enhancement I suggested to the development team, that was accepted and implemented: originally, the main Marionette window, pictured in Illustration #1, below, titled each of its main window button sections with the cryptic labels "Source Selects" and "Source Controls": Screen capture of Marionette main screen, before my enhancement. Illustration #2, below, shows my improved labeling, now clearly and unmistakably telling the user what the function of each button grouping is: Screen capture of Marionette main screen, after my enhancement. Much better. Take this principle of unmistakably clear and logical communication, apply it to an entire help file, technical document, or any other kind of print or online information vehicle, and the following benefits occur immediately:
I'm ready to assist you in assigning these benefits to your company and your product lines(s). Please contact me right away! |
||
WRITING SAMPLE #2 Help File for "SIMPL Windows" Software Program SIMPL Windows is a complex software development tool for the programming of touch-control and other automated systems manufactured by the Crestron corporation, "SIMPL" being an acronym for Symbol Intensive Master Programming Language. I wrote most of the Help system for this product. The file was too large to easily reproduce here, but is a relatively quick download (Windows .zip file, under 300K, 60-seconds at 56k). After download, to display the Help file properly, be sure to extract the files by right clicking the .zip file and selecting "Extract All" (do not merely double-click the .zipped folder, and do not select "Open With" or "Send To"). [NOTE, APRIL 2024: As this Windows Help file is based on a now-defunct Microsoft Help engine, WinHlp32.exe, it cannot easily be opened under later versions of Windows, these being, I believe, Vista, as well as systems 7,8, and later.] Here is the main Help window: SIMPL Windows main Help window. This main Help window is deceptively concise and simple: there is actually a large body of complex, detailed technical information contained beneath its surface. By design, however, each Help file Contents window, starting with this one, is cleanly, clearly, logically, and elegantly-named and presented, providing a friendly and accurate path for the user into every descending level, below. |
||
WRITING SAMPLE #3 MacOS Technical Reference Manual v2.0 This is a 25-page operating system diagnostic manual I voluntarily researched and composed in 1996, detailing troubleshooting, diagnostic, and maintenance routines, and a list of Web-based technical and other resources and related information and data, for Macintosh users. The manual was available for download on America Online, and garnered 1,476 downloads in its first thirty days online. Please note that my present computing platform is Windows XP Professional. The original download included a comprehensive, methodically-presented Read Me file, which is also contained, here. I have additionally included a several-page file description, from which I culled my final AOL file description, posted online for users to help them assess the resource prior to downloading. Please note that what appear as formatting errors in the technical reference manual download, occur because the document was originally formatted for a then-popular Macintosh booklet-production program called DOCMaker. When displayed and printed in the DOCMaker format, the presentation of content is perfect. Moreover, in that format the content formed a booklet, instead of a long document, as presented now. The complete file, presented here as a writing sample, is an instantaneous download (Windows .zip file, under 50KB, 01 second at 56k). Here is a reproduction of the cover: Cover of Mac OS v2.0 Technical Reference. |
||
WRITING SAMPLE #4 (A GROUP OF SAMPLES) Software Alpha and Beta Test for "DateView" Software Program OVERVIEW
Bill Davis was my contact person for the duration of the testing. At its conclusion, Mr. Davis very willingly affixed his signature to a strong, glowing, and detailed letter of reference for me (available for review), based on my work during the test. One of the reasons I thought to request a recommendation was that over the months he made a number of favorable remarks regarding my testing efforts, including these direct quotations: "You will probably be selected as a tester...I'll try to get you on the list as you give excellent feedback." "I wish we had about ten more testers like you! You're giving us so many good reports I'm having trouble keeping up." "Lots of good info in that report. It's been passed along." "...I'm embarrassed at not being able to answer all your messages in detail immediately, because you're doing such as wonderful job. I figured it's the least I could do to acknowledge that we'd gotten the message and appreciated it..." "...considering the high quality effort you are putting into beta testing for us...Thanks again!" "Thanks for beta testing on the holiday...Thanks for the continued excellent feedback. Keep it coming!" |
||
WRITING SAMPLE #4a DateView Bug Report #9 As originally submitted to the Prairie Group. I've called this a bug report, but as it turns out, I think it's more of a usability & features report. Had the following four event listings set to carry forward each day: Date, From-To, Duration, Description: Jul 8, 1995 12:00 AM - 12:00 AM 0:00, General, *DAILY SCHEDULE PT/1*
Date, From-To, Duration, Description: Jul 8, 1995 12:00 AM - 12:00 AM 0:00, General, *DAILY SCHEDULE PT/2*
MARKET: Jergens f/bathroom/2 Dawns/Raisin Bran/2% milk/bananas/plates/apples/frozen yogurt/heavy-duty scrub sponge/Neutrogena s & c/Wet Ones/small oj's It is now Sunday, July 9 1995, and none of these events have carried over to today. They were all set to "Repeat: never", but that shouldn't matter, as far as I know. They were X'd off to "Carry forward." (A few minutes later...) I guess that I just figured out this problem, but I'm not happy with the answer, operationally. It seems that you have to quit DV, and relaunch it to get the "carry forward" events to move to their new, proper day (right?). It is so common for people to work right through midnight, it would be much better if the program just did the switch without having to relaunch it. This means that users now have to actively *remember* to quit, then relaunch the program every night at midnight, if they want an up-to-date calendar! This is not ease of use! |
||
WRITING SAMPLE #4b DateView Bug Report #18 As originally submitted to the Prairie Group. I am double-clicking on the very first entry for Friday, Aug 25, and its dialog box is not coming up. Nothing at all is happening. The entry is: TODAYS MICROLIST: Get:
(A few seconds later...) In an attempt to get the program responding, so I could copy the above contents, I double-clicked the entry directly underneath the above entry, which did respond by bringing up its dialog box. I was then able to double-click the original event bloc and open it. I realize that in doing this I may have disturbed the internal state that caused the non-response, but it was a judgment call. I considered it important to copy the event text, to insure that you knew exactly which event I was talking about. Perhaps next time I'll see if I can't just describe the event, or just directly copy as much of the text as I can see without trying to force open the dialog box. |
||
WRITING SAMPLE #4c Features & Usability Report #1 As originally submitted to the Prairie Group.
As the wording for an IT reminder this is sufficient. Once the events are plugged into Hornet, however, this wording appears not only (possibly) in a reminder that appears *before* the event, but also in Hornet right in the calendar event box for the actual event date, when it then makes no sense--when this same message is read in the calendar event box for Thursday itself, it gives the misleading impression that the trash barrels must be taken out on *Thursday*, not Wednesday. I don't see how this is anything but a substantive problem. As indicated, this is part of the general problem of trying to "straddle" the wording of reminder messages to accommodate the future tense requirement of a pop-up reminder, against the present tense requirement of the actual event date message itself, right in Hornet. I have addressed this larger issue at length in a previous Usability Report (dated 5.3.95) as follows: Problem: For a given event, I want the message text for the reminder to be different from the message text for the calendar, which the program won't allow. This is necessary for two reasons.
Before using DateView, I had InTouch set up so that I received very polite, automated-sounding reminders, almost as if my computer was talking to me, reminding me to do this or that. It was great. Now, I can't do that anymore (not unless I want to take up more space on my calendar, anyway). For me, this is a pretty noticeable gap in using DateView for reminders. The usability of my system as a whole has been chipped away at. My taxes are due on the 15th of April. I therefore want to set a reminder to appear three months in advance, stating "Please complete and return your federal and state tax forms. They must be received by April 15th." Quite a reasonable reminder, right? However, the only way to use this wording for my reminder is to also use it for my calendar message text, which would obviously be inappropriate! It would be ridiculous for my calendar message text for April 15th, which needs to be present tense, to contain the same message that the reminder does; reread the message above and you'll see. The calendar message text just needs to say something like "Tax forms due today", present tense. However, the reminder text needs to be future tense. When using InTouch alone, I did not have this problem, as there is no calender text, only reminder text, so you can use future tense for all reminder wording. The only way to have a system which uses the same wording for both areas is if the system is a more-or-less crude PIM system, at least in this regard. On page 21 of my DateView 1.0 manual there is a sample reminder alert box, with the message text reading "Don't forget to call Fred". If this reminder pops up 30 or 60 days in advance, this message will be meaningless, as there is no detail. For it to be meaningful, it would have to give the user more information, for example "Don't forget to call Fred, your broker, by June 1, as he said that by then he'd have three excellent stock offerings to show you." That would be a meaningful reminder, but there's one little problem--this exact reminder wording will also show up in the calendar message, which would be inappropriate. The crude solution forces the user to accommodate the burden of: Both of these elements explain why I say that using the same wording indicates a "crude" system. An interim solution that I have devised is to include text for both calendar (present) and reminder (future) messages when writing the event message, which then appear in both the reminder *and* the calendar text. Here's a real-life example: Reminder: Please continue cleaning out the basement and garage tomorrow; put out bulk waste then also, for Thursday's pickup. Calendar: basement cleanup/bulk waste out today All of this text then appears in both the calendar and the reminder. Do you see the problem here? The only real solution that I can see: Allow the user to write two different message texts for an event, one for the calendar; one for the reminder.
More to come. Best, Vince |
||
WriterForHigher.com |