My first love was short fiction writing. Still love it. Fiction writing gives me the ability to understand things from a target audience (or character’s) POV. Looking at content, whether fiction/nonfiction, from different angles helps me communicate more effectively.

Fiction skills–plot, characterization, POV, structure–are basic to any type of writing. Characterization applies into how you talk about content to your target audience (POV, character). What does that reader need to know? In what order (plot/structure) and how much (plot)?

Poetry classes taught me the value and weight of each word. Poetry makes you look at editing with a different philosophy: how does the word sound? how is it better than another? Concrete images in poetry improve fiction descriptions. Poetry made my writing succinct.

Nonfiction taught me how to combine the different disciplines to communicate a message effectively. Also, awareness of words’ connotations. Is it the best choice to use a word with baggage? Being sensitive to how a reader will react to an article helps word choice.

Journalism taught me the importance of reliable sources and solid references. This also ties in with nonfiction, when writing research articles. Don’t just take someone’s word for it. Check their sources or citations to confirm. For fiction, get your history write.

And finally tech writing, which is how I earn a living. Don’t write fiction in tech writer voice. A procedure is like explaining a story arch to another user in short, succinct steps in plain English. Evaluate content that could be expressed in text, graphics, diagrams.

When I was a tech writing team lead, I took all the writers to go to a local writing conference so our team could go and be *writers*. No session restrictions. The goal was to expand their skills. Get outside of your primary discipline to get a fresh perspective.

Having some understanding of multiple writing disciplines means you have a good toolbox for communication. Poetry skills make me an effective editor for short fiction. Research skills give me an edge in peer reviews and editing. Fiction gives me a framework for tech writing.

And, at heart, this is what it means to me to be a writer: being an effective communicator of whatever content I’m creating. Fiction and poetry are art forms–so are tech writing, journalism, and nonfiction. Tech writing and fiction are strong points, but I’m capable in other disciplines. That makes me a versatile, employable writer. Writing lets me write about all of the topics I love. I wanted to be a fiction writer, but opted for tech writing to support my horse habit. Find your joy. Find your voice. And write.

What does that mean for this site? I’m going to shift my content towards technical writing in general and share experiences I’ve had as a technical writer, technical editor, and as a project manager. Face it, every tech writer ends up doing doc project management so you learn those skills.

Mostly, I want to write and share some of the joy I find in this field. I love what I do. I love telling stories (aka procedures) with protagonists (users) defeating evil monsters (problems) through magic (troubleshooting).

It’s my jam.

Google offers remote desktop support for machines using Google Chrome browser.

1. With both devices on the same wifi network, go to remotedesktop.google.com/support
2. Select Remote Support and install the Chrome extension on both tablet and desktop or laptop.
3. After the extension is installed, use the Share This screen option.

For more complete instructions, see https://techwiser.com/share-screen-chromebook/

First tip: Make sure you have a good network of other writers, editors, and graphic designers. These contacts can be a primary source of new jobs. Having a list of other freelancers you can pass along clients to when your own docket is full is a good thing. Down the road, that writer you sent a client to will probably pass a client back to you. Attending writer-focused groups, like the Society for Technical Communication meetings, are great resources for meeting other writers. My contacts through STC have been invaluable for job leads, new clients, and other professional opportunities.

Second tip: Look for leads by going to where your potential subject matter experts hang out. These are the people who could need your services. Networking sites like LinkedIn and MeetUp have groups listed for just about every topic and profession. For example, if your specialty is software documentation, then look for a Meetup group for software developers so you meet the people who will know about upcoming projects requiring a writer. These individuals might not be the people who are capable of hiring a contractor. If a developer is threatened with documentation, you bet the dev will remember your card and will hand it to the manager.

Third tip: Target small companies and startups who might need writing for small or short term jobs. As a freelancer, one of your “valud-add”s is that you can provide services to a company without adding to the personnel overhead. Small businesses, new startups, or even startup think-tanks locally might need your services but can’t afford to have a writer on staff. Research the companies and find out which ones look promising for your own background. For example, in Research Triangle Park, NC, the Triangle Startup Factory provides opportunities for new businesses. Local newspapers carry stories on current crops of companies — plus those who have “graduated” from the program.

You can also find more potential clients using the Chamber of Commerce and other news sources. Be creative. Look for the people who write the type of software (or whatever) that you specialize in. Do your homework on a company before approaching them.

The installation instructions for PloneSoftwareCenter state to add Products.PloneSoftwareCenter to the eggs = section of the zinstance/buildout.cfg file in the Plone installation. Unfortunately, this method failed due to missing dependencies in my Plone installation.

Figuring out dependencies

Each time I ran the buildout command, I received an error message similar to this one reported on the PloneSoftwareCenter issue #84:

2009-02-24 10:03:06 ERROR Application Could not import Products.PloneSoftwareCenter
Traceback (most recent call last):
File "/home/encolpe/zopes/ve-p31-eurocontrol/management/parts/zope2/lib/python/OFS/Application.py", line 709, in import_product
product=__import__(pname, global_dict, global_dict, silly)
File "/home/encolpe/.buildout/eggs/Products.PloneSoftwareCenter-1.5-py2.4.egg/Products/PloneSoftwareCenter/__init__.py", line 15, in ?
from Products.PloneSoftwareCenter.content import validators
File "/home/encolpe/.buildout/eggs/Products.PloneSoftwareCenter-1.5-py2.4.egg/Products/PloneSoftwareCenter/content/__init__.py", line 7, in ?
import root
File "/home/encolpe/.buildout/eggs/Products.PloneSoftwareCenter-1.5-py2.4.egg/Products/PloneSoftwareCenter/content/root.py", line 22, in ?
from Products.ArchAddOn.Fields import SimpleDataGridField
ImportError: No module named ArchAddOn.Fields

The last line indicates that ArchAddOn.Fields was missing. A quick search for ArchAddOn revealed a Products.ArchAddOn, with a few of these hits also referencing PloneSoftwareCenter. I received a similar error for fancyzoomview and AddRemoveWidget.

Procedure

To get PloneSoftwareCenter working, I added the following lines to the buildout.cfg file in the eggs section:

eggs =
. . .
Products.PloneSoftwareCenter
collective.fancyzoomview
Products.ArchAddOn
Products.AddRemoveWidget


Running the buildout and instance commands then started Plone so I could use the portal_quickinstaller in the Zope Management Interface (you.site.address/manage) to activate all of the packages. The Software Center then appeared under the Add New menu on the Plone site.

Tip: If you are behind a proxy server, make sure you export your proxy server using the command line option export http_proxy=proxy.addy.com. Make sure you replace proxy.addy.com with the appropriate proxy address.

(This post originally appeared on my other blog, ceffyl.net.)

PHC has compatibility issues with Plone version 4. This information is no readily apparent on the PHC project page. Installing PHC on a Plone 4 installation running on a Mac OS X 10.6.5 server took quite a while due to tracking down errors.

PHC will work with Plone 4 if you install PHC as a development egg using the SVN trunk. Development eggs override eggs listed in the eggs section of the buildout.cfg file.

Background

According to posts found on the Plone Product Developers list, the released, final version of Plone Help Center (PHC) listed on the project page is not compatible with Plone 4. (Cyn.in, a Plone 3-based environment, also has problems running PHC.)

If you try to install PHC using buildout or non-buildout methods (i.e., in the Products folder), you will most likely receive the following error message: AttributeError: type object 'BrowserDefaultMixin' has no attribute '__implements__'.

Requirements

To get Plone Help Center working with Plone 4, you will need:

• Access to the Plone 4 installation with permissions to edit files
• An available text editor
• The address of the SVN PHC trunk: http://svn.plone.org/svn/collective/Products.PloneHelpCenter/trunk/

Procedure

This procedure assumes that you have a running, properly configured Plone 4 installation, are familiar with editing files and using a Unix terminal. While this procedure is written for OS X, it should be compatible with other Unix or Linux. Commands used for Windows will be different, however, the general method should still work.

Instructions for adding the development eggs are based upon Plone’s Installing a third party product article.

In the example procedure below, Plone was installed as a stand-alone instance (non ZEO Cluster).

1. Log on to the Plone server.
2. Change directory to the Plone installation folder (replace with the appropriate username: cd /Users//Plone/zinstance
3. Stop Plone: ./instance stop
4. Change directories to src and checkout a copy of the PHC from SVN.
   
cd src
svn co https://svn.plone.org/svn/collective/Products.PloneHelpCenter/trunk/
   Note: You may need to change the folder name from “trunk” to Products.PloneHelpCenter.
5. Move up one directory: cd ..
6. Create a a backup of the buildout.cfg file: cp buildout.cfg buildout.backup
7. Edit the buildout.cfg file. Add the Products.PloneHelpCenter to the eggs section and the development egg location created earlier to the develop section:
   
   [buildout]
   ...
   eggs =
   ...
   Products.PloneHelpCenter

   develop =
src/Products.PloneHelpCenter

8. Save the file and exit the text editor.
9. Run the buildout command from the zinstance directory to update Plone: ./bin/buildout
10. Start Plone: ./bin/instance fg
11. Log on to Plone’s Zope Management Interface (ZMI) by opening a browser to http://your.site.address/manage.
12. On the left side, expand the tree under the name of your site.
13. Click on portal_quickinstaller and click the checkbox next to PloneHelpCenter under Installable Products. Press Install.
14. Log on to the Plone site. Help Center should be listed as one of the options under the Add New menu.

(This article originally appeared on my other blog, ceffyl.net.)

I tried to install the OS X installer and chose the local installation option. The installation process never completed. About halfway through the installation process I received the following error message:

Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: Copying buildout skeleton
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: Fixing up bin/buildout
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: Running buildout; this takes a while...
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: Buildout returned an error code: 1; Aborting.
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: Buildout failed. Unable to continue
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: Installation has failed.
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: See the detailed installation log at /tmp/install.log
Nov 8 14:13:34 bibracte installd[71515]: ./postinstall: to determine the cause.


The /tmp/install.log file indicated that the Zope 2.12.10 Python distribution was missing.

Detailed installation log
Starting at Mon Nov 8 14:13:34 EST 2010
Creating directory '/Applications/Plone/zinstance/parts'.
Creating directory '/Applications/Plone/zinstance/develop-eggs'.
Couldn't find index page for 'Zope2' (maybe misspelled?)
Getting distribution for 'Zope2==2.12.10'.
While:
Installing.
Getting section instance.
Initializing section instance.
Installing recipe plone.recipe.zope2instance.
Getting distribution for 'Zope2==2.12.10'.
Error: Couldn't find a distribution for 'Zope2==2.12.10'.


Quick search for solutions did not return an easy way to install Zope 2.12.10, except by using MacPorts (which requires XCode and XWindows). One article that mentioned possibly using the unified Linux installer. I created a Ubuntu virtual machine (VM) using Parallels for the Linux Plone version and downloaded the unified installer for Linux. Surprise! The readme file for the Linux installer indicated that it could also be used with Mac OS X.

I followed the command line instructions (copied and pasted code) to install and configure Plone. I reviewed the config file Plone/zinstance/buildout.cfg and it looked okay so I did not run the buildout process. Ran the command to start Plone: /Plone/zinstance/bin/plonectl start and received an error message:

bibracte:PLone-4.0.1-UnifiedInstaller $ /Plone/zinstance/bin/plonectl start
instance: . . Traceback (most recent call last):
File "/Plone/buildout-cache/eggs/zdaemon-2.0.4-py2.6.egg/zdaemon/zdrun.py", line 745, in
main()
File "/Plone/buildout-cache/eggs/zdaemon-2.0.4-py2.6.egg/zdaemon/zdrun.py", line 742, in main
d.main(args)
File "/Plone/buildout-cache/eggs/zdaemon-2.0.4-py2.6.egg/zdaemon/zdrun.py", line 241, in main
self.run()
File "/Plone/buildout-cache/eggs/zdaemon-2.0.4-py2.6.egg/zdaemon/zdrun.py", line 245, in run
self.opensocket()
File "/Plone/buildout-cache/eggs/zdaemon-2.0.4-py2.6.egg/zdaemon/zdrun.py", line 267, in opensocket
sock.bind(tempname)
File "", line 1, in bind
socket.error: [Errno 22] Invalid argument
. . . . . . . . .
daemon manager not running


The above error message (“socket.error”) indicated that maybe something was wrong with the network settings in the Plone config files. I went through the config file (mentioned earlier) and through the zdrun.py file and did not find anything wrong. The instructions that I followed from the included Readme.html file did not indicate that a web server should be started with Plone. Mac OS X Server has a built-in web service, which was started and properly configured. I only wanted to run Plone on localhost.

On a hunch, a quick web search turned up other installation instructions on Red Turtle for OS X that included and different start instructions. Running these commands finally got Plone up:

• Run the buildout: ./bin/buildout
• Start Plone: ./bin/instance fg
• Then type this URL in your browser: http://localhost:8080

Update: This post was originally post on my other blog, ceffyl.net. An OpenID user commented that they verified the 4.0.1 installer for OS X is complete (includes the correct Zope version) and that the “Unified” installer worked with OS X with XCode.

Want to learn more about how Doc Box Consulting can create a top-notch content solution for your project? Contact Doc Box Consulting.

W3Schools is a good site with excellent tutorials for HTML, CSS, XHTML, among others. I learned HTML/CSS there — and then had to unlearn some things. W3Schools is geared towards coding towards Internet Explorer, which doesn’t necessarily match the actual W3C specs.

An easy way to play with CSS is to start with standards-compliant templates that work in a wide range of browsers.

• Two column templates
• Three column “holy grail” template
• Examples and templates, plus some good info on the box-model hack (thanks IE)
• Box Lesson for easy to use templates
• Layout Reservoir from Blue Robot

Get a good CSS editor like TopStyle from Bradsoft (http://topstyle4.com) that has a list of selectors as drop-down boxes — that way you don’t have to memorize things. There used to be a freeware version, TopStyle Lite, that provides a good starting point.

Western Civ, creators of Style Master CSS editor, has an excellent tutorial for CSS.

A List Apart is probably the best place to find information on best design practices and how to work around common problems. Cutting edge stuff by some of the best in the industry.

Eric Meyer’s home page has a great set of links for CSS references and related items.

Want to see what CSS can really do? Take a look at CSS Zengarden and CSS Vault. Some excellent examples of how CSS can completely change the appearance of a page by swapping the CSS without touching the page’s code.

CSS Layout for Fun and Profit (glish.com) also has great articles and information.

Once you have a CSS sheet created, it should be validated against the spec (this is also a great troubleshooting tool) by using the W3C CSS Validator.

If you really can’t find something, chances are that “Holy CSS, Zeldman!” has a link to it.

• My bookmarks on Delicious for tech writing
• The motherload of all TW mailing lists: TechW-L. Great articles, resources, and mailing list archives. The membership includes several thousand tech writers world wide.
• Online text book for tech writing
• Fundamentals of Document Design by BA Stoky Design
• Monster.com’s Guide to careers in tech writing
• DocSymmetry’s info on being a tech writer
• Myths about tech writing
• Webster Tech Writing (see the field guide to tech writing)
• User Guide Tutorial from Klariti

To get ideas for manual layout and structure, take a look at some of the available free templates for Open Office Writer and Microsoft Word. For Word, check out Microsoft’s Office template pages. The exact URL will differ depending upon the version of Office you have installed.