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