Re: Writing samples and portfolios

["Janet Swisher" <jmswisher -at- gmail -dot- com>]

I think it depends on the project, and especially on whether the
developers are aware of the need for documentation or the limitations
of their existing documentation. Large open source projects are more
likely to have this awareness and possibly an existing subproject for
documentation. Smaller projects that know they need writers sometimes
post on the SourceForge Help Wanted section:
http://sourceforge.net/people/

Open source projects depend heavily on community, and a tech writer
needs to become part of that community. There is nobody signing all
the paychecks to make developers pay attention to you. As Gene says,
you need to become involved in the same way as any other contributor
--- download and install the software (which may involved building it
locally), try it out, and ask and answer questions. As a tech writer,
you will notice as you do this what information is lacking or
confusing. But waltzing into a project and announcing "Your
documentation sucks" is not going to win a lot of cooperation.

One of the beauties of the FLOSS Manuals project its use of the "book
sprint" model for bringing together SMEs and writers interested in a
project, to focus on documentation for a limited time period. In
particular FLOSS Manuals' founder Adam Hyde has a talent for finding
open source projects that need doc help, and convincing the technical
experts to participate.

On Mon, Dec 1, 2008 at 8:38 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
> I think this unlikely in most open source developments,
> where the developers often only "explain things" to each
> other through the message boards.  A tech writer would
> need to self-familiarize with the project the same way its
> developers and users do - by downloading the various
> builds, installing them, using them and scanning the
> message boards for discoveries made by everyone else
> on the project.
>
> Gene Kim-Eng
>
>
> ----- Original Message -----
> From: "voxwoman" <voxwoman -at- gmail -dot- com>
>> I wish more tech writers would document open source software, because the
>> documentation that is there reads like it was written by developers. Do
> you
>> have experience with the open source community - are the developers
> willing
>> to spend time explaining things to the writers so the writer can write
> about
>> it?
>



-- 
Visit my blog at: http://www.janetswisher.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing 
solution. Author in Doc-To-Help's XML-based editor,  Microsoft Word or 
HTML and publish to the Web, Help systems or printed manuals. 
http://www.doctohelp.com

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
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-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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