Comments on: A Possible New Step in the Writing Process http://www.gryphonmountain.net/2009/09/a-possible-new-step-in-the-writing-process/ Technical Communication and Other Writing Topics (by Ben Minson) Thu, 9 Sep 2010 15:59:36 -0500 hourly 1 http://wordpress.org/?v=3.0 By: Margaret http://www.gryphonmountain.net/2009/09/a-possible-new-step-in-the-writing-process/comment-page-1/#comment-34522 Margaret Thu, 03 Sep 2009 16:52:42 +0000 http://www.gryphonmountain.net/?p=731#comment-34522 I think we should write all user manuals, tutorials, help, or step-by-step procedures as close to a conversational style as possible. I try to write as if I were standing behind someone and personally walking them through the process. I also try to put in plenty of screens or fragments of screen shots so they can compare what they get after each step to confirm that they are in the right place. For IT or technical types, I draft the docs the same way, but then extract each installation or configuration procedure to a checklist with a block for installer and system/network/ terminal/client identification, and date and initial verification fields for each section, so that the checklist becomes a verification record that the installation was completed, when, and by whom. And it can easily be returned to for completion if the installer was interrupted during the process. I think we should write all user manuals, tutorials, help, or step-by-step procedures as close to a conversational style as possible. I try to write as if I were standing behind someone and personally walking them through the process. I also try to put in plenty of screens or fragments of screen shots so they can compare what they get after each step to confirm that they are in the right place.

For IT or technical types, I draft the docs the same way, but then extract each installation or configuration procedure to a checklist with a block for installer and system/network/ terminal/client identification, and date and initial verification fields for each section, so that the checklist becomes a verification record that the installation was completed, when, and by whom. And it can easily be returned to for completion if the installer was interrupted during the process.

]]> By: Gordon http://www.gryphonmountain.net/2009/09/a-possible-new-step-in-the-writing-process/comment-page-1/#comment-34494 Gordon Thu, 03 Sep 2009 08:17:26 +0000 http://www.gryphonmountain.net/?p=731#comment-34494 Interesting. I've challenged my team to write up a couple of short (1-2 page) overviews of distinct areas of the product, with a conversational slant. The aim is to get across some of that useful information that is a bit grey, and not the stuff we'd normally have in the formal product documentation. This might be a good way for them to focus their planning though. Interesting.

I’ve challenged my team to write up a couple of short (1-2 page) overviews of distinct areas of the product, with a conversational slant. The aim is to get across some of that useful information that is a bit grey, and not the stuff we’d normally have in the formal product documentation.

This might be a good way for them to focus their planning though.

]]>