January 14, 2013

Technical Writing Tools

Posted in Content Management, writing tagged at 1:27 am by mknight1130

Technical writers need flexible tools to collaborate with their peers and to ensure their words reach readers. No longer do writers and readers confine content to a piece of paper. They interact with content and reuse it in a variety of contexts. To meet these demands, a technical writer requires a good content management system. Confluence and Framemaker are examples of two such applications.

Confluence, created by Atlassian, combines desktop editing  functionality with dynamic capabilties to interact with other team members. Confluence users can edit documents quickly by using macros to replace content and to automatically upload documents. Writers use Confluence to keep the look and feel throughout a set of documents and to pull excerpts from one section or file format to another.  This tool allows content to remain fluid and usable among different types of content, while still maintaining the overall integrity of the document. Confluence power allows more than one writer to edit a document while maintaining the changes from each. Writers can use confluence to assign and manage tasks, obtain comments from their peers, contribute feedback, and track their content evolution. Confluence allows team members to search for particular content and task status while notifying others of updates. Writers can use this tool to look up technical requirements, forming the backbone of help content. Confluence users will find a power and ease in writing about and accessing technical knowledge.

Framemaker , produced by Adobe.com, uses XML (Extensible Markup Language) and DITA (Darwin Information Technical Architecture) to define and use content elements. Content from one document can be searched and applied to a different context, such as a pop-up from hovering over an image. Through XML and DITA, Framemaker enables the writer to specify a hirearchy of elements, allowing for consistency among descriptions and content placement. Readers in return, can easily access documentation through a variety of media, including cell phones and Kindles. Moreover, Framemaker authors can upload a variety of media, including videos and images, to enhance their writing, making content dynamic. Content, created through Framemaker, can be transferred easily across different file formats and documentation structures, while maintaining consistent terminology.

Framemaker and Confluence provide technical writers tools to make content dynamic and accessible by a wide audience.



January 6, 2012

Beyond the Pen: Electronic Writing Resources

Posted in writing tagged at 11:29 pm by mknight1130

I recently received an Amazon Kindle for the Holidays. Immediately I downloaded many favorite books; these include Ghost  Story, by Jim Butcher and several Sherlock Holmes mysteries. As I am reading on my Kindle, I am amazed at how this electronic book reader changes reading and writing. I prefer short passages that are easy to scan. I practice keeping my writing brief. As I am thinking about writing, here are some excellent sources on online writing.

Colorado State University (CSU) has a great series of writing guides, including 3 on writing for the Web, See: http://writing.colostate.edu/guides/index.cfm?guides_active=web&category1=39 . Readers will gain understanding of how print and online writing compare and are different.  In addition, the website provides comments on common etiquette. The CSU guides also provide a list of handy resources to learn more about online writing, see good writing samples, using HTML to write on a web page,   and sample different approaches to designing web pages

For some good practices towards online writing, the NOF-digitise Technical Advisory Services provide a guide, Writing for the Web, at http://www.ukoln.ac.uk/nof/support/help/papers/writing-web/ .  Although this is an older document, the guidelines and general principles apply today. In addition the guide provides tips on describing online images and tailoring text to different audiences, making content more readable.

I think the writing guides from Colorado State University and the Writing for the Web, are good starting places to learn about online writing. I look forward to see additional writing resources for alternative platforms. Maybe the next writing guide will describe how to capture readers using a cell phone to retrieve information quickly.


March 16, 2009

Resources on writing well

Posted in writing tagged , , at 3:28 am by mknight1130

Recently, I have been writing a lot: thank you notes, resumes, cover letters, updates, and email replies. It seems like my hands are either glued to the typewriter or to my pen. I thought I would share some writing resources that make my pen sing.

The first site is a dictionary compendium called Onelook Dictionary Search at http://www.onelook.com/ . Onelook provides a search engine for words. Word definitions, spellings, and translations can be found at OneLook. If the word interested or exciting is used too many times, then entering that word into Onelook will provide the key to a Thesaurus  and alternative words. For words that are constantly mispelled or misued, such as restaurant or occurred, affect, provides a spelling and usage confirmation. I find the Onelook site to be invaluable in checking paragraphs and in writing well.

The second site is the Strunk, William Jr., 1918, The Elements of Style at http://www.bartleby.com/141/ . The website and book, The Elements of Style, are a fundamental reference to using English properly. There is a search form for grammatically related questions, such as commas or colons. The search results list web articles that explain the grammatical rule and provide an example of usage. This site is a gem in writing well and in further developing a writing style.

I plan on using the Onelook Dictionary Search and the Strunk, William Jr., 1918, The Elements of Style as I develop my writing style.