Developing documentation, the FLOSS way  Clip to Evernote

I enjoy reading about the processes used by other technical communicators and those working on various types of projects. Not everyone will tackle a project in the same way, and there’s often something to learn (or at least to get me thinking) by studying someone else’s approach.

While the Free/Libre/Open Source (FLOSS) community is sometimes seen as a bunch of unguided missiles heading towards the same target, it’s actually more structured than that. This guide, from the Fedora Project, is a detailed look at one approach a FLOSS project uses to develop documentation.

Weekly links roundup  Clip to Evernote

  • Gordon McLean points out that we shouldn’t put so much emphasis on tools; we really need to focus on the problems that we’re trying to solve.
  • Sarah Maddox writes about being an agile technical writer.
  • Ellis Pratt muses about how a new technology from Nokia could reinvent the user manual.
  • Really Strategies has an older, but still relevant and readable, introduction to wikis.
  • if you use Word, you’ll want to read this article on correcting automatic numbering in lists.
  • In a short video, Stewart Mader discusses using “a wiki to collaboratively write, edit, and assemble documentation,” and to consider letting your audience contribute as well.

Wikis won’t kill documentation  Clip to Evernote

Over the last couple of years, I’ve heard more than a couple of people say that the wiki will kill (or at least bite into) so-called traditional documentation. I’ve never subscribed to this point of view. While I could spend several thousand words explaining why, someone else has done it for me. Just read this blog post by Craig Haiss.

Usability and Open Source software  Clip to Evernote

One complaint that’s often made about free and Open Source software is that its usability is lacking. This article by Celeste Lyn Paul (who works with a number of Open Source projects) takes a look at usability in Open Source software.

She notes:

Being a designer in an open source project is not easy. For many years, usability specialists were disregarded, under appreciated, and ignored. This attitude probably sounds familiar to many of you because it was not too long ago that professional usability specialists encountered the same resistance.

That observation also applies to the development of a lot of commercial and in-house software, too. And it’s not just the designers and usability architects who face the obstacles. Technical communicators who act as user advocates (and shouldn’t we all?) often face an uphill battle against developers in this situation, too.

Why Open Source content management?  Clip to Evernote

This article, at The Content Wrangler, offers three compelling reasons:

  1. Open source solutions are often a better fit
  2. Open source solutions are often standards-based
  3. Open source solutions are more transparent

While Open Source may not be the best solution for an enterprise, in any area, the solutions available are definitely worth a look.

Baselining documentation on a wiki  Clip to Evernote

Like them or not, wikis are becoming more and more common in various enterprises. And they’re not just a developer’s tool anymore. They’re used fairly extensively for documentation, too. The beauty of wikis is that they’re easy to use and that they’re living documents. The content on a wiki is constantly being updated and (you hope) refined.

The dynamic nature of wikis, though, can cause a few headaches when you need to baseline documentation that’s on a wiki to correspond with the release of your product. That’s the problem that we ran into at the firm at which I’m working right now.

Continue reading
http://www.dmncommunications.com/weblog/?p=lfbxoqpfqwoe&paged=124
www.dmncommunications.com
crawl=CC-MAIN-2014-42
43131
application/http; msgtype=response
sha1:FTXHNAOBCIDJCBCGF2HTBXZ445BJ5Y7I
<urn:uuid:89f7f866-ba87-4af9-aee2-3967a0c9cdff>
2014-10-31T21:16:49Z
69.163.144.236
sha1:MJQBI3FPNJCBPPGRRLYKUDXAGZH32ELX
<urn:uuid:56645e94-ee92-42cf-b1cb-d1ece955454e>
http://www.dmncommunications.com/weblog/?p=lfbxoqpfqwoe&paged=124
response
<urn:uuid:a1e73eed-25af-4547-b22f-67bcbbb383c7>
robots: classic
hostname: ip-10-16-133-185.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2014-42
operator: CommonCrawl Admin
description: Wide crawl of the web with URLs provided by Blekko for October 2014
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf