Re: "You are what you document" - blog post

Subject: Re: "You are what you document" - blog post
From: Lois Patterson <loisrpatterson -at- gmail -dot- com>
To: Tony Chung <tonyc -at- tonychung -dot- ca>, techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 13 Jun 2014 12:36:50 -0700

> Of course, I could be partial to the mindset of this article as I'm a developer
who masquerades as a technical documentor.

I'm partial to the mindset because I have been working on what is
essentially developer-oriented documentation, and in an environment where
developers are deeply involved in the creation of documentation, for a
rather long time now.


On Fri, Jun 13, 2014 at 12:33 PM, Tony Chung <tonyc -at- tonychung -dot- ca> wrote:

> Even though the article was written by a developer with an intended
> developer audience, there is much the TechCom community can learn from this
> practice.
>
> 1) Know your audience: if you are writing code for developers to use your
> product API, know that newcomers can't start with the reference manual.
> They need practical tools and sample projects to play with and learn for
> themselves. Then they will be in a better position to know what to look for
> in the reference material that will help them create your docs.
>
> 2) Coach your developers: Too often subject experts get focused on the one
> thing their feature does, at the expense of figuring out how their piece
> fits into the overall scope. Developers need to think more
> entrepreneurially, and almost evangelistically, about how their little
> piece needs to be used in order that the rest of the project makes sense.
>
> 3) C-Suite Speak: make sure you can explain the product in terms the
> executives can understand. Often called the 20,000 ft view, the readme
> should explain what your thing is, what it does, and why yours and not
> someone else's.
>
> 4) Further to readme-think being helpful: If your company uses agile
> development practices, train developers to write clear user stories. You
> can then extract some of the material for the readme, release notes, and
> concept documentation, even while the product is still in development.
> Conceptually, the product shouldn't change drastically up 'til release.
> (This is how I would have fought for readme-first documention.)
>
> Of course, I could be partial to the mindset of this article as I'm a
> developer who masquerades as a technical documentor.
>
> Cheers,
> -Tony
>
>
>
> On Friday, June 13, 2014, Sion Lane <sion -dot- lane -at- unit4 -dot- com> wrote:
>
> > I found the article to be very biased towards developers, and not
> > particularly useful to documentation professionals in general.
> >
> >
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Doc-To-Help 2014 v1 now available. SharePoint 2013 support, NetHelp
> enhancements, and more. Read all about it.
>
> Learn more: http://bit.ly/NNcWqS
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as loisrpatterson -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Doc-To-Help 2014 v1 now available. SharePoint 2013 support, NetHelp enhancements, and more. Read all about it.

Learn more: http://bit.ly/NNcWqS

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Previous by Author: "You are what you document" - blog post
Next by Author: Re: "You are what you document" - blog post
Previous by Thread: Re: "You are what you document" - blog post
Next by Thread: TechWhirl: Technical Communication Recap for June 13, 2014


What this post helpful? Share it with friends and colleagues:


Sponsored Ads