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: Bad Documentation and Linux From:"Jon Leer" <jleer -at- leertech -dot- net> To:"'Janet Swisher'" <jmswisher -at- gmail -dot- com>, "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 7 Dec 2009 08:41:34 -0500
The deal is that many developers don't see the point of having a
non-developer document what they do. Yes, they will add comments to the
code... And that really is all the documentation that is necessary (from
their viewpoint).
Jon Leer
Leer Technical Communications
Bedford, NH
603-315-4029
jleer -at- leertech -dot- net http://www.leertech.net
Technical and Business Communication Consulting:
Technical - Manuals to Online Help
Business - Marketing Communication
Content Management - Knowledge Base Development and User Experience
> -----Original Message-----
> From: techwr-l-bounces+jleer=leertech -dot- net -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+jleer=leertech -dot- net -at- lists -dot- techwr-l -dot- com
] On Behalf Of Janet Swisher
> Sent: Friday, December 04, 2009 5:58 PM
> To: Richard L Hamilton
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Bad Documentation and Linux
>
> On Fri, Dec 4, 2009 at 4:34 PM, Richard L Hamilton
> <dick -at- rlhamilton -dot- net> wrote:
> > Sourceforge is a great starting place. You can also go to
> the web site
> > for any of your favorite open source applications, and you
> will nearly
> > always find a call for help from writers.
>
> Projects that don't have a call for writers on their website
> are probably not ready to be helped by writers. If you're
> already involved in a project's community, you can try to
> convince them to let you help them, but if you're just
> looking for a project to help, you're better off moving on to
> one that knows it needs you.
>
> In particular, on SourceForge, look at the Help Wanted section:
>http://sourceforge.net/people/
>
> Occasionally, when I hear about an open source project that's
> looking for writers, I'll mention it on Twitter (@jmswisher),
> but there are many that I don't hear about.
>
> > That said, I'd suggest you start by checking out
> > http://flossmanuals.net. It's a great project that documents a wide
> > range of open source projects, with the resulting documents being
> > open-sourced, too.
> >
> > The project is worth checking out even if you're not interested in
> > writing for them now. They have a lot of existing books covering
> > software you may be using. It's also worth checking out the
> interface
> > they use for contributors. It's a wiki-based platform that
> is easy to
> > use.
> >
> > They are always looking for contributors and give full attribution.
> > They also periodically host book sprints, which sound like a blast.
>
> Thanks for the mention. There's a book sprint this coming
> week (December 7 to 12) for "Squeak Etoys" educational
> software, which sounds like especially a blast. There's no
> in-person meeting for this sprint -- it's all happening
> online. Details at:
>http://wiki.squeakland.org/display/sq/Book+Sprint
>
> >
> >> -----Original Message-----
> >> From: techwr-l-bounces+dick=rlhamilton -dot- net -at- lists -dot- techwr-l -dot- com
> >> [mailto:techwr-l-bounces+dick=rlhamilton -dot- net -at- lists -dot- techwr-l -dot- co
> >> m] On Behalf Of Dan Goldstein
> >> Sent: Friday, December 04, 2009 2:23 PM
> >> To: techwr-l -at- lists -dot- techwr-l -dot- com
> >> Subject: RE: Bad Documentation and Linux
> >>
> >>
> >> New tech writers often ask TECHWR-L how they can break into the
> >> business. I always point them to SourceForge, where they
> can work for
> >> free, build up a portfolio, and then bring that portfolio to
> >> interviews for paying jobs.
> >>
> >> > -----Original Message-----
> >> > From: Dana Worley
> >> > Sent: Friday, December 04, 2009 1:02 PM
> >> > To: techwr-l -at- lists -dot- techwr-l -dot- com
> >> > Subject: Bad Documentation and Linux
> >> >
> >> > ... It does point out there is a need in the open source
> community
> >> > for technical writers. Not that it will pay the
> mortgage, but think
> >> > of the glory ;)
>
> Ironically, the article doesn't actually make that point. It
> laments the lack of good Linux documentation, describes the
> problems with developers writing docs, and then issues a call
> to users to start documenting. The writer seems to have
> missed the possibility that tech writers could help with this
> situation.
>
>
> --
> Visit my blog at: http://www.janetswisher.com
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Are you looking for one documentation tool that does it all?
> Author, build, test, and publish your Help files with just
> one easy-to-use tool.
> Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:
>http://www.doctohelp.com/
>
> Help & Manual 5: The all-in-one help authoring tool. True
> single- sourcing -- generate 8 different formats and as many
> different versions as you need from just one project. Fast
> and intuitive. http://www.helpandmanual.com/
>
> ---
> You are currently subscribed to TECHWR-L as jleer -at- leertech -dot- net -dot-
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
>http://lists.techwr-l.com/mailman/options/techwr-l/jleer%40lee
rtech.net
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/ for more resources and info.
>
> Please move off-topic discussions to the Chat list, at:
>http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
>
Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: http://www.doctohelp.com/
Help & Manual 5: The all-in-one help authoring tool. True single- sourcing --
generate 8 different formats and as many different versions as you need
from just one project. Fast and intuitive. http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
