WriterForHigher.com


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 window.
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 window.
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:

  1. Better, easier-to-use products that customers will gravitate toward, resulting in a tenaciously loyal user base.

  2. Unavoidably increased and sustained word-of-mouth from very happy users, and impressed reviewers, resulting in greater market share.

  3. Significantly lower technical support costs, as customers find they have little or no need to pick up the phone, no matter their level of expertise or previous experience using your product.

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:


Screen capture of the main window for the SIMPL Windows help system.
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


Screen capture of DateView main screen.
Screen capture of DateView main screen.



OVERVIEW

  • I authored Pre-Alpha, Alpha, & Beta Test Reports For Macintosh "DateView" product, 1995 - 1996, published by The Prairie Group, Inc., Des Moines, IA. (http://www.prgrsoft.com or click image above).
  • DateView is the scheduling component of a two-program PIM system; it is presently marketed for "time management." The other component is InTouch, marketed for "information management."
  • Pre-release code-name for DateView was "Hornet."
  • Because of the nature of the product, my own personal information regarding scheduling, remindering, and to-do's had to appear in my reports.
  • Reports submitted through pre-alpha, alpha, and beta phases of product design, in 8-month test.
  • My analysis resulted in substantive change to product interface.
  • Reports include: 30 bug reports and addenda; 15 "Features & Usability" reports and addenda; 2 documentation reports; 1 interface design report.
  • All reports available for review.


  • FURTHER REPORTS PENDING HERE

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*

  • morning: stretch/walk
  • afternoon: job search/ph calls/stretch-vocalize-sing
  • evening: read/write/clean room/learn lyrics/job search
  • up 7 AM
  • walk 8 AM
  • eat 9 AM

Date, From-To, Duration, Description:  Jul 8, 1995 12:00 AM - 12:00 AM 0:00, General, *DAILY SCHEDULE PT/2*

  • work on address notifica's
  • (make phone calls)
  • work on Mac skills
  • lunch 1:30
  • job search 2:30
  • dinner 6:30
  • walk around park? 7:15
  • political reading/writing 9 PM
  • lights out 11 PM

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
GROCERY: tamale pies/vegetable pot pies/bathroom towellettes

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:
  • Norton/SAM upgrades
  • ClickBook
  • Mac Prog f/Dummies
  • Help! Mac Answer Book
  • Mac networking book
  • Thigh pillow (& travel cup)

(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.

  1. In the Hornet main window, the 'Week' arrows are counterintuitive. The down arrow clearly should move to the previous week, "down" roughly equating to "backward", and the up arrow should move the subsequent week, "up" roughly equating to "forward". They currently operate in the reverse manner, however. Think of each equating to its opposite in these terms, as the program does, and you may see what I mean. I also recollect this problem from my past use of Hornet months ago.

  2. There should be text in the upcoming Hornet manual revision to apprise of the possible need to change the wording of various event and/or reminders, when InTouch reminders are plugged into Hornet. This is to accommodate the change in time perspective that may occur once a given reminder is converted to an InTouch event. Here is a brief example:

    In my neighborhood, the trash is collected on Mondays and Thursdays. When using IT 2.0.8, therefore, with reference to Thursday's "take out the trash barrels" reminder, I made Thursday (every Thursday, actually; I made this a repeating event) the actual event date, and I set a reminder to go off on Wednesday, to remind me to take out the barrels that day, for Thursday's pickup. The reminder read:

    Please put out the trash barrels. Do this early in the day...

    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.

  1. The calendar text usually needs to be very concise, for space reasons (and I have a 15" monitor); it is sharing space with other event messages for one given day. The reminder, however, has no such limitation; it is therefore possible to word reminders in a more complete, pleasing, and automated-style fashion. For example, my calendar wording will read 'put recyclables out', whereas my reminder will pop up and say to me 'Please put the recyclables out; this includes paper, cardboard, and glass.'.

  2. 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.

  3. The other problem with having the same wording for both the calendar text and the reminder text is even more severe. Here's a real-life example:

  4. 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:

    1. Wasting time playing around with the wording to find a phrase or two that straddles both present and future tense, and

    2. Actually using wording that is not as targeted and accurate as it should be.

    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.

  1. Additionally:  Page 30 of the docs states that if 'Gray out the past' is enabled, several things will occur, including "...all time prior to the current time will appear grayed-out in your calendar." I am now in List Display mode, with two events listed in the Hornet Main Window for Tuesday July 4th (What a trooper: he even pre-alpha tests on a holiday!), and that date is grayed out up to the very bottom of the box enclosing the second event. I submit, however, that graying out in List Mode is more-or-less meaningless, and even potentially confusing, as there is no time indicator to determine the relative meaning of the gray vs. the white area.

More to come.

Best,

Vince






WriterForHigher.com