Ramsden.info – for technical writers

Technical writing repository

This site is intended as a repository of information for technical writers. It started out in life as a readily accessible (web-based) place to store technical writing tips and tricks, how to do this and that, using the tools at my disposal, and has evolved into a virtual warehouse of technical writing resources. Technical writing is all about taking potentially complicated technical subject matter and conveying it in an uncomplicated manner so that non-technical people can understand and use it.

There is always more than one way to do something, and most often the simplest way is the easiest and best. Why complicate things? Keep it simple. That's what I've done with this web site. Kept it simple.

This site is living proof that you don't need a complicated or expensive toolset to create and maintain a modern website. Everything you see here was created using inexpensive low technology (lotech) tools.

That provided the inspiration for the site name.

Who am I? > find out more

See Also

Top Site Topics (most visited pages)
Word of the week
Quotable Quotes
Commonly confused words
Commonly confused phrases
Understanding HTML
Writing Rules
'Business English' Writing Workshop—Stage One

Book Reviews

See Also

See which book reviews are planned, underway or coming soon

Quotable Quotes
Writing Rules

Help Authoring

Microsoft Windows ships with proprietary built-in help engines to display custom help for Windows compatible programs (software designed to operate in the Windows Operating System environment).

WinHelp (Windows Help) was designed for operation with 16 bit WIN9x versions (Windows 95, Windows 98, Windows ME), and was superseded by HTMLHelp (HTML Help) designed for operation with 32 bit WIN2X (Windows 2000, Windows 2002—XP) and later. All these versions of Windows provide backward help compatibility, so will display both WinHelp and HTMLHelp. Both types of help are created by separate Help Workshop packages freely available from Microsoft for help authors.

Microsoft Help II (MSHelp2) is the next generation help designed for operation with 64 bit Windows.NET (codenamed Longhorn) slated for release in 2005—delayed to 2006—which (apparently due to negative feedback) has subsequently been restricted to authoring from only within the Microsoft software developer environment Visual Studio.NET and with no separate help authoring tool being made available for help authors. MSHelp2 has elements which are XML based to enable functionality in VS.NET, however, there are no XML authoring capabilities exposed for the help author in this release.

I have authored help in all three environments, and have experienced the good and the bad of each. Each type of help has its own idiosyncrasies and behaviours. Listed below are some of the help authoring matters which required particular attention to successfully achieve, some tips and tricks I've found along the way, and further information about Windows help authoring:

Working with Graphics

The writing is on the wall

Technical writers often need to work with graphics as an integral part of their job. There are very many graphic editing tools available, and each has its speciality and purpose. Knowing which graphic editing tool is the most suitable to use in a particular situation, is the "art"—pun intended—of an experienced technical writer.

Equally important is knowing about the available graphic file formats available, and which is most suitable for the intended purpose of the graphic and the delivery media. There are several different graphic formats available, each providing a different purpose and functionality:

• Bitmaps are pixel maps of an image which store the colour and brightness of each and every pixel in the image. This is highly accurate, however, necessarily presents the image at a fixed resolution directly determined by the number of pixels used. A larger image requires more pixels and so produces a larger file size to store all the pixel information. Thus, bitmaps files are generally the largest of graphic file types, and are less suitable for online downloads than smaller file sizes are.
• GIFs are for animations, solid-color images, and images with repetitive color, such as line art and logos. GIF supports transparency and are generally compressed into a smaller file size then JPEGs. GIFs are not recommended for photograph reproductions. 
• JPEGs are for continuous tone images, such as photographs. JPEG compression preserves a broad range of color and subtle variations in brightness, but does not support transparency. JPEGs tend to produce larger file sizes than GIFs.
• PNG-8s are for solid-color images with sharp detail. Note that many older browsers do not support the PNG format.
• PNG-24s are for continuous tone images, such as photographs. PNG-24 preserves transparency, a broad range of color, and subtle variations in brightness.

Notes

• All versions of Microsoft Windows come with a basic bitmap editor called 'Paint'.
• Many older browsers do not support the PNG format.

To determine your ideal image format, consider how your image is going to be used (for example, in Web or Print form) and what type of image it is (flat color vs. continuous tone). It's best to save images with large areas of flat color as GIF or PNG-8 images. Save other images, such as those with color gradients or other continuous tones, as JPEG or PNG-24 files.

Writing Resources

Writing resources are everywhere. The internet has opened millions of libraries and billions of personal resources to anyone with access to a web browser. A search for a simple phrase on a search site like Google will produce literally hundreds of thousands of search matches (hits).

Writing resources range from your personal (undocumented) experiences in your head, through to well structured documents on specialist topics written by knowledgeable and professional writers. For the technical writer, the process of researching a particular topic can be achieved (with the aid of the internet) in under a day, whereas this (now readily available) broad range of information was simply inaccessible in print libraries and reading facilities available to the researcher of the past.

Writing Tools

Writing tools for technical authors are many and varied, each providing different benefits to writers. Some are very specific, providing a particular purpose—like Microsoft Frontpage which produces HTML pages for websites, and others are very general providing multiple purposes—like Microsoft Word which produces office related documents ranging from address labels to multi-page reports. Still other tools are used for book publishing—like Adobe FrameMaker, and graphical page display layout—like Adobe PageMaker or Quark QuarkXpress.

It is a relatively simple matter to choose the tool which is appropriate to your writing needs. The first step is to accurately assess exactly what your writing needs are and will be in the foreseeable future. If you don't know what you're trying to achieve, you can hardly choose the right tool to achieve it, can you?

See Also

Working with Visual Web Developer
Problems with Visual Web Developer

Working with Expression Web
Problems with Expression Web

Please wait while description loads...
If nothing happens for a while, please refresh the page.

Printing and PDFs

Programming and Scripts

Web log (blog)

Milk Crates (September 2005)

Drinking (October 2005)

Technical Writing (November 2005)

Industrial Relations (December 2005)

Low income markets (January 2006)

Effective Managers (February 2006)

Effective Communication (March 2006)

Plain English Writing (April 2006)

Writer Training (May 2006)

Advanced Technical Writing (June 2006)

Technical Writing Roles (July 2006)

The Importance of Quality Practices (August 2006)

Technical Writing Essentials (September 2006)

 'Business English' Writing Workshop—Stage One (October 2006)

[coming soon] 'Business English' Writing Workshop—Stage Two (November 2006)

 Understanding encoding character sets in HTML (December 2006)

 Colour by number (January 2007)

 Scripting differences between Browsers (February 2007)

 Browser versions (March 2007)

[coming soon] Surviving the migration to Expression Web (April 2007)

[coming soon] Creating websites for family and friends (May 2007) 

 Understanding PhotoVoltaic (PV) system rebates (June 2007)

 How to solve Rubik's cube (July 2007)

 Working with DIVs using only CSS (August 2007)

 Employment Agencies (September 2007)

 Understanding Digital Ethnography (October 2007)

 Microsoft PC-vs.-Mac OS (November 2007)

[coming soon] A new Australian Federal Labor government (December 2007)

[coming soon] Australian workplace reforms (January 2008)

[coming soon] Understanding JavaScript strings (February 2008)

[coming soon] Creating DHTML multiple columns (March 2008)

[coming soon] Microsoft Vista Migration (April 2008)

[coming soon] Providing breadcrumb links for your users (May 2008) 

See Also

Word of the week
Quotable Quotes
Commonly confused words
Commonly confused phrases
Writing Rules

Contact me here

off the shelf

so many decisions???

we're artists,
not just painters

quiet! please

the dirty end

Gutenberg's printing press

to be, or not

inner thoughts

News and Views

The end of FrontPage

According to Microsoft's FrontPage Insider Newsletter dated April 5, 2006:

"The FrontPage era is ending, but two great new tools are born. Explore the next generation of Web authoring tools from Microsoft and unleash your creativity to design professional sites."

Read my synopsis at The future of FrontPage 

In July 2006, Microsoft Expression Web Designer (EWD) 'Community Technology Preview' version 1 was announced as a free trial tool, available to the general internet public for download, testing and review. 

Update

As of September 2006, the product was renamed "Expression Web" and upgraded to Beta 1 version.

Read my synopsis at Expression Web Designer

See Also

Working with Visual Web Developer
Problems with Visual Web Developer

Working with Expression Web
Problems with Expression Web

Keeping up-to-date with mobile technology

Have you ever wondered about the technical details of a lightweight Windows Operating System designed for small portable devices? Wonder no more. Microsoft released on September 14, 2006 an online video explaining everything you wanted to know about Windows embedded OS's, and more. It's a staggering 24 minute show.
According to Microsoft's MSDN Flash Newsletter dated Fri 13th October 2006:

A Look at Windows Embedded Operating Systems

Mike Hall discusses Windows CE, Windows XP Embedded, and Windows Embedded for Point of Service, where these operating systems might be used, which technologies are unique to each operating system, and also walks through the tools for the Beta release of Windows CE 6.

"Today we're going to be taking a walk through the embedded operating systems that are available from Microsoft. There are three which include Windows CE, Windows XP Embedded and Windows Embedded for Point of Service."

"Hi, my name's Mike Hall, I'm a Senior Technical Product Manager in the Mobile and Embedded Devices group. This is a division at Microsoft that deals with embedded operating systems and mobile devices."

"So I guess the first question is why does Microsoft have three embedded operating systems?  Well, let's talk about the differences between each of the operating systems and that will give you a good idea why we have each of these three and how they fit into the general embedded space." 

Download the MSDN TV episode to your hard drive from: http://www.microsoft.com/downloads/details.aspx?FamilyId=8411DB15-1F3C-487F-A8CE-A20A3DF1CAEB&displaylang=en.

The full transcript is available from Microsoft at A Look at Windows Embedded Operating Systems

What is WinFX -The New Programming Interface Introduced in Windows "Longhorn"

Learn about the object-oriented, managed API for the breadth of Windows "Longhorn" and how it relates to the work you may already be doing on the .NET Framework. The video runs for just under 10 minutes.

"Hello. I'm Brad Abrams, I work on the Common Language Run Time Team here at Microsoft. Today, we're going to talk about what WinFX is."

"Before we get into the details of WinFX, I wanted to talk about the history that led up to the development of WinFX. If you look back, it was in 1993 that we introduced the Win 32 API, it was the first time we exposed it to developers. And we later shipped it with the Windows 95 release. So it's been well over 10 years since we introduced the Win 32 API, and it's certainly time for us to refresh the developer view of the platform."

"The other interesting thing is that platforms live for a long period of time, so we have to make sure that as we build the new platform, it has a good longevity to it and it'll live for a long time."

"So what's WinFX? Well, WinFX is an object-oriented API that leverages the .NET framework and exposes the breadth of Longhorn, the breadth of the operating system to developers. I'm super excited about this API, because it's the first time we've really invigorated the core APIs to Windows so that application developers can access the breadth of Windows in a way that's object-oriented. Which means that all the classes are available to sub-class and extend; that you're able to customize solutions. It's available in managed code, and that gives you the security and the reliability and the robustness that you expect from managed code. And it's built on and extends the .NET framework. So if you're familiar with the .NET framework today you're going to be right at home with WinFX."

Download the MSDN TV episode to your hard drive from: http://www.microsoft.com/downloads/details.aspx?FamilyId=E16CA43C-0B35-4F1A-BAC5-C413F3311E92&displaylang=en.

The full transcript is also available from Microsoft at What is WinFX?

Deep thought and reflection on matters of interest.