Categories

April 2014
M T W T F S S
« Mar    
 123456
78910111213
14151617181920
21222324252627
282930  

Technical Writing Services

Based in Research Triangle Park, North Carolina, Doc Box Consulting offers freelance technical writing services and web site development and maintenance at a reasonable cost. Technical writing is about translating complex concepts into plain English, at a level appropriate for the target audience. With over 10 years experience as a technical writer, Kim Nylander, the primary writer for Doc Box Consulting, can help you create materials best suited to your project.

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

Tips for searching for clients

Part of the challenge and the frustration of freelancing full time is finding new clients. The majority of my clients are from word-of-mouth referrals from previous clients, other writers, and people I’ve met through alternative networks.

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.

Installing PloneSoftwareCenter on Plone 4

In addition to the Plone Help Center, I also wanted to have PloneSoftwareCenter for project management capabilities. PloneSoftwareCenter is used to manage the software projects on Plone’s web site.

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.)

Installing Plone Help Center on Plone 4

Plone Help Center (PHC) is a Plone module used on the Plone site to handle community documentation and support site. The module comes with predefined FAQ, How-to, Tutorial, Reference Manuals, Error Reference, Links, and Glossary Definitions.

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.)

Installing Plone 4 on Mac OS X Server 10.6

Plone 4 is an open source content management system (CMS). It’s an elegant, extensible solution for document and content control. Large companies, including Apple, use Plone. I’m evaluating CMS solutions and was pleased to find that Plone has a Mac OS X installer.

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.

Links for learning CSS

A friend of mine asked for tutorials and resources for cascading style sheets (CSS), so I complied the following list of sites. The most comprehensive place to start is by reviewing the CSS specification (current version is 2.1). The spec is published and maintained by the World Wide Web Consorium (W3C), which also a tutorial on CSS.

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.

Continue reading Links for learning Cascading Style Sheets

Suggestions for new technical writers

Interested in learning about technical writing or getting started in the field? The set of links below were put together when a friend asked me for information on technical writing.

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.

Creating Unique Headers and Footers in Writer

You create unique headers and footers in one document in Open Office Writer (Writer) by using the page styles available in Writer. Page styles in Writer are like creating master pages in InDesign: page features (text, graphics, etc.) are stored in the style. When a page style is active on a page, the style name is highlighted in the Page Styles pane of the Styles and Formatting palette.

Header and footer text associated with a particular style is entered on a page tagged with that style.

The procedure below describes how to create new page styles, apply the page styles, and then modify the headers and footers associated with each page style. You can also use this procedure with existing page styles by starting after after the first section.

Continue reading Creating unique headers and footers in Writer