Business and Technical Writing

Business and Technical Writing

A common thread across most activities I have been involved with is being able to communicate in concise and simple to understand ways.  The need for good written documentation spans industries and disciplines.  From business plan writing, sales collateral, technical writing to email campaigns - the quality of the written documentation often plays a huge role in determining the effectiveness of the activity.  In business terms, complete and well written documentation directly translates to profitability.

In addition to properly organized (and conveyed) thoughts and ideas, the choice of media needs to match the application.  Some of the more common media types I have worked with include:

  • Portable Document Format (PDF): the preferred format for documents that either need to be available offline, or printed.  Adobe PDF format is an industry de facto standard, with free readers readily available.  When properly indexed, large documents such as manuals or books can be easily navigated (see writing samples below for examples).  PDF documents are simple to exchange via email or to publish on the web.
     
  • Print: documents needing professional printing often require special formatting and handling.  Bound documents such as manuals and books have special margin handling needs.  Depending on the style chosen, they may need special header and footer handling.  Preparation of electronic files to be submitted to printers need to take into consideration tools available to the printer, including proper fonts.  Other issues include paper and document cover types and materials, and packaging.  Current advances in web technologies now allow for increased use of HTML/CSS (see the printed form of this page for an example).
     
  • Web: the preferred format for documents that need to be displayed on the world wide web.  Advances in Cascading Style Sheets (CSS) and CMS systems (such as the one this site uses) allow for rich formatting with minimal fuss.  Should the document requirements be more  sophisticated than current web techniques allow, PDF can always be used as a backup strategy.
     
  • Electronic Mail: rich (HTML) formatting of documents is often needed for customer communication.  The formatting of HTML email has its own set of issues specific to common email clients.

Writing Types

Different writing styles and approaches are appropriate depending on the target reader.  A sales brochure for consumer electronic products is written in a completely different way than a complete business plan targeting the business investor community.  Technical writing targeting corporate system engineers will be written in the language familiar to them (technical jargon).  A university thesis will target the educational community as well as professionals in the given area of study.

Regardless of the target audience for a given document, there are many issues common across most document types.  These include:

  • Know your readers
  • Proper organization of thoughts and ideas
  • Concise and simple to understand wording
  • Correct spelling and grammar

Some of the more common writing types that I have been involved with are business plans, marketing and sales literature, technical writing, and educational.   Each is described in more detail below.

Business Plans

Business plans are special documents used for the planning and monitoring of a business.  They are often used as tools for obtaining loans and/or investment funding for a company, although strictly speaking, this should be their secondary role.

In-depth knowledge of the relevant products or services, competition, market factors, marketing plans, internal resources, sales projections, and complete financial information are just a few of the areas that need to be well understood.  An external consultant can be quite helpful for teams not experienced in complete business planning to ensure that all the basic areas are covered.  This includes proper financial modelling of the business.

Marketing and Sales Literature

Sales writing is directed towards the customer of the business.  This goes for direct sales letters (either print or email) as well as brochures or any other written correspondence.  In the case of letters and email, the message must be direct and personal, as well as simple and to the point.  Key selling points directly related to the buying decision must be made obvious, and a sense of urgency established.  Other sales collateral, such as brochures or data sheets, are focused on providing the customer with enough product information to make a knowledgeable buying decision.  They must be complete and accurate.  Inaccurate of incomplete information can often result in a poor impression of the company in the eyes of the customer, hurting the sales process rather than helping.

Technical Writing

During my 25+ years work on Internet technologies technical writing has been a constant part of many projects.  While in the USA, I worked with technology companies to produce both internal technical documentation and user manuals for their customers.  This work was extended during my IMA days, where I was responsible for all technical documentation, including user manuals, release notes, white papers, and sales literature.  This was not actually by design, but made necessary as finding skilled technical writers with the engineering expertise to understand what they were writing about was almost impossible to find in the region.  Some of the resulting documents can be found at the bottom of this page.

Educational

Local universities and secondary schools often require detailed material be prepared in English.  This can range from school papers to thesis work.  While I do not provide research assistance for such projects (students are always responsible for their own work), I can help in formulating and organizing ideas and the conveyance of these into written documents.   This is similar in nature to copy editing (described below) with the exception that the process is done hand in hand with the student.

Copy Editing

Copy editing is the task of taking existing draft documents and improving them for the purpose of eventual publication.  Copy editing generally does not result in any basic changes in content, but focuses on formatting, style, language use, and grammar.

Copy editing is extremely important for documents that undergo translation by someone not intimately familiar with the subject material or whose language skills are not native.  Typical examples are website content, product manuals, sales literature, and email correspondence.

Sample Documents

Network Management Tutorials and Papers (2014)

These technical papers are the most recent and are being actively maintained and written.  The papers are specific to the Zabbix Network Management system.   The complete index of all documents being worked on is at Tim's Zabbix Tutorials, Whitepapers, and other Resources.

Web Sites

  • Tim's Place - this site - responsible for all site design and content.  Moved from Druapl 6 to WordPress 4.2.2 in July, 2015.
     
  • SZTeachers - An education site for Shenzhen, China. The eventual design calls for integrated classifieds and teaching resources.  The site is a multilingual Drupal 7 responsive site with both Chinese and English language content using common URL's. Responsible for all design and English language content. The site is no longer being actively maintained pending review on how best to move the site forward.
     
  • Jade Connections - Jade Connections was established in 2004 as an Internet consulting and services company focusing on delivering system and network solutions.  The current focus is in the areas of network management (on-site and remote), network and host based security and in the design and deployment of a scalable and cost effective enterprise class cloud computing infrastructure.  Other projects include the design and implementation of highly integrated and scalable collaborative social networking web environments as well as Voice over IP (VoIP) solutions.  DNS, web and email services are provided for several organizations in the region.  This site was rewritten and updated in July, 2015.
     
  • Jade Networks - Jade Networks, a division of Jade Connections Limited, provides the network infrastructure for Jade Connections.  This includes custom on-site and remote network monitoring services.  Jade is responsible for the off-site remote service monitoring for MONIC, the Macau Domain Registrar. All DNS, web, and email services are continuously monitored around the clock with alerts being sent to both MONIC and Jade staff when potential problem situations are detected.  This site was rewritten and updated in July, 2015.
     
  • Jade Networks Operations - this is the networks operations site for Jade Networks.  Details about network operations and the network management platforms and list servers run under this domain.
     
  • International Messaging Associates - this is an archive of the site as it appeared at the end of 2003 when the company was shut down.  Site design (graphics and css work) done by external consultants.  Responsible for all other content.  This is a static site written in HTML.  The format of this site is quite dated but has a good document archive.
     
  • RegainAmerica - RegainAmerica is designed to be an open community collaborative/distributed authoring environment dedicated to effecting positive change on the local, state and national levels. The first phase of this free collaborative environment will empower members to freely voice their concerns on issues that are important to them. More importantly the goal of RegainAmerica is to provide a platform where people can not only freely exchange ideas and views, but work together to effect real change.  This is a work in progress - responsible for all site design and implementation.  Current prototype based on Drupal 7.  Articles written by site contributors.
     
  • PinoyTalk - PinoyTalk was designed with the initial implementation rolled out at the end of 2005. Focused on the Philippine market, it served as a functional prototype for future highly integrated social networking sites. Philippines was chosen due to its close proximity to Hong Kong, very low costs of promotion, maturity in terms of use of social networks, and existing infrastructure (very low startup costs). PinoyTalk services included integrated email, chat rooms, forums, distribution lists, games, a basic meeting point, and a place-holder for an online store. The site was taken down in 2011 with its future status still under consideration. The graphics work was done by a colleague in the Philippines, but all other content and application integration done by myself.  The old site was replaced by a place-holder page pending redesign decisions.
     
  • Connie's Corner - Personal website for Connie Kehres.  Based on Drupal 6.  Currenting assisting Connie in the redesign using WordPress.

User Manuals, Release Notes and White Papers

Documents provided here are from the work done with International Messaging Associates.  The IMA products were designed for technical datacenter managers, and were written with them in mind. Additional documents can be found on the IMA Archive Site.  The format of this site is quite dated but has a good document archive.

Sales Documentation

Other