Technical Communication Camp

Software Documentation and Agile

2010-03-29T16:47:00Z

Developing documentation (both end-user and internal) in an Agile software development environment can present a few challenges, but overall presents many opportunities for technical communicators.

Agile, by its nature, provides relatively short cycles for developing end-user documentation. However, Agile projects succeed or fail based on their internal documentation, so technical communicators are a required part of the process. In fact, we are involved from day one.

Overview of Agile

When I was first introduced to Agile over 10 years ago, the original "Agile Manifesto" for software development (http://agilemanifesto.org/) struck a bit of fear in my heart. The Manifesto values "Working software over comprehensive documentation." But the seventeen signatories were not referring to end-user documentation, but internal documentation. (After I started breathing again... I learned more. Our company's owner had purchased each team member one of the few books on Agile available at the time and made it required reading. There has been quite a bit written since.)

Key principles of Agile include:

· Small, self-organizing teams

· "Just enough" internal documentation

· Willingness (and the ability) to change direction quickly

(A list of all the principles can be found here: http://agilemanifesto.org/principles.html)

Among the methodologies used are:

· Scrums (short, daily meetings)

· Kanban planning (a visual, flexible task management system)

· Sprints (very short – usually 2 week – cycles for software deliverables)

Bottom line, the Agile method attempts to keep everything lightweight and flexible. This requires that team members work closely together plus – and this is key – are dedicated participants in the process.

How Technical Communicators (TCs) Fit in the Process

TCs get involved in the development process from day one, because each Agile team includes a technical communicator. This is partly because Agile teams are cross-functional; but also because the internal doc for the project must be captured. This doc is needed for the project stakeholders, the organizational memory, and for audit purposes (this is dependent upon the industry you are working in).

Documenting for the organization memory is important to the process, because Agile strives for continuous improvement that will increase both the speed of development, and the quality of the software. Project artifacts are needed to achieve that goal.

End-user documentation for the project is a given, but its development must be adjusted to the Agile process. The biggest process change for TCs is that user documentation must be written in small pieces — before the entire project is scoped. Also, detailed requirements documents are replaced with user stories.

One thing that should feel familiar: user documentation will always be one Sprint (iteration) behind.

In an Agile process, end-user documentation should be ready for and included in the usability and quality assurance reviews. This feedback can be used to improve the documentation, plus it raises its visibility to the entire team.

As for internal documentation needed, the list includes:

· User Stories (requirement docs)

· Acceptance tests (testing docs)

· Project planning information (stored initially on white boards, post-its, index cards, etc.)

· Reference documentation/code comments

Some of these are very simple to take on, but some will take a little creativity. For example, if your team is keeping planning information on a whiteboard, you may need to take photos of the board every day or week, and store that information for future reference. Creating reference documentation and capturing code comments can be handled automatically, depending upon your help authoring tool.

How Doc-To-Help Fits Agile

You can capture software reference documentation (namespaces, classes, methods, properties, etc.) and code comments automatically, with the right help authoring tool. Doc-To-Help can handle this, plus there are other ways it meshes well with the Agile process.

#1 — You can store all of your project docs (internal and external) in the same Doc-To-Help project. Docs can be Word, HTML, or XHTML (XHTML docs are edited in Doc-To-Help's built-in editor). You can mix doc types in the same project. Bottom line, everyone on the project can write in the format they are most comfortable with.

#2 — Using conditions, you can mark entire documents for either internal or external use. Then you can build the output you need for either purpose based on those conditions. You can even create conditions for "testing," "requirements," "planning" — whatever you wish (and that includes the end user docs). Outputs include HTML Help, browser-based Help, pdf manual, Word manual, and more.

#3 — Doc-To-Help has source control. If you need document check-in/check-out to avoid editing conflicts, you can use Doc-To-Help's built-in source control, or take advantage of its interface to Microsoft Team Foundation Server.

#4 — Creating reference documentation and capturing code comments is easy, because Doc-To-Help includes a Microsoft Sandcastle plug-in. This puts a Wizard-like interface on creating reference documentation. All that is needed from software development is the .NET assembly file and the XML comment file. (By the way, software development can use ComponentOne IntelliSpell to check their code comments in advance.)

#5 — If you need automated builds, Doc-To-Help includes a utility that you can use to build outputs in batches.

#6 — As the project hits specified milestones, you can use Doc-To-Help's "Save Project" feature to save the internal and external documentation for that cycle, and then you can continue on with the next. This will preserve the project documentation for later reflection (see the Agile Principles) plus you will have a record for both organization memory, and perhaps the auditors.

Wrapping up

Within an Agile environment, our TC challenge is to provide end-user documentation, while learning about and taking on new responsibilities. In the end, project knowledge must be documented for Agile to work. Although Agile emphasizes keeping documentation "light," internal doc is a must for stakeholders, and the organizational memory.

Remember, as in any process, Agile has specified guidelines and methodologies – but you need to tailor it for your situation. Be flexible and make it work for your project.

This post touches on a very small portion of Agile and its theories. The websites below are a great starting point for learning more.

Further Reading

http://www.agilemanifesto.org/

http://www.agilealliance.org/

Styles – Why use them?

2009-11-17T14:45:00Z

In Doc-To-Help, you apply Styles to your Source documents so that your Target output will look and behave the way you prefer.

That's one good reason to use them, but not the only one.

Another very good reason is because Styles enforce consistency. If you create a Style for highlighting items in your user interface (for examples, toolbar buttons, dialog box names, windows, etc.) and that style uses a specific font, font color, and it's bold – you can name it "UI Element" and you and everyone on your team can use it. OR you could write up a post-it note to remind yourself that UI Elements are Verdana + dark blue + bold. And then send everyone on your team an email that lets them know this is the standard (or note it in your Style Guide).

But when you apply local formatting (AKA "in line" or "ad hoc" formatting) without using a Style, you don't have a standard. You simply have a guideline. And it is easy to forget guidelines.

In addition, if you had created a Style in the first place, you could easily change what "UI Element" looks like by updating the Style. If you want to switch from dark blue to green, you simply update the Style. You don't have to comb through all of your source documents and fix each UI Element individually.

That being said, you can choose *not* to use Styles ... in that case you can use the Formatting buttons in all three of the editors in Doc-To-Help. If you are using Word, most of them can be found in the Formatting toolbar (Word 2003) or the Font and Paragraph ribbon groups in the Home tab (Word 2007). In Adobe Dreamweaver and Microsoft FrontPage, you will use the Formatting toolbar (FrontPage) or the Text menu (Dreamweaver).

In the Doc-To-Help XHTML editor, you will use the Formatting ribbon group on the Editor tab.

In the XHTML Editor, there is a slight difference between the buttons to the left of the Local Formatting button, and those to the right, however. The ones available to the left of the Local Formatting button (bullets, numbering, bold, italic, subscript, superscript, and more) may be applied to your document and the document will still conform to the W3C XHTML 1.0 Strict Specification. This is because those options are part of that specification. If you click the Local Formatting button, additional options for applying formatting without styles will be revealed. These options are: font name, font size, text align left, text align center, text align right, text align justify, highlight color, font color, underline and strikethrough. If you use these options, your document will no longer conform to the W3C XHTML 1.0 Strict specification; it will switch to the Transitional specification.

Just a note before using the Local Formatting button …. If you use Local Formatting options (font name, font size, text align left, text align center, text align right, text align justify, highlight color, font color, underline and strikethrough) then turn off Local Formatting by clicking the button, all of the formatting applied with the local formatting options will be removed, returning the document to the Strict specification.

Long story short (well, maybe it is too late for that) – using Styles are an important "best practice" when working on a Doc-To-Help project. But Doc-To-Help still lets you use Local (ad hoc, in line) Formatting in any editor if you would like. Because we want you to have options, and work the way you want to. J

Creating renewable content – “Green” authoring

2009-09-25T18:14:00Z

Those who adopt “green” lifestyles try to recycle and reuse as much as possible, preserving resources for future generations.

By the nature of what we produce, Tech Comms can't create content that will last for generations to come, but we can create content that is "green" by adopting reuse strategies. And writing once and reusing many times is not only efficient, it cuts down on errors.

One of the best ways to create reusable content is to save content “chunks.” These chunks can be long or short and they have two added benefits:

The content only needs to be updated in one place, no matter how many times it is used within a project.
It ensures consistency, since core information will be the same within and among projects.

To chunk your content in Doc-To-Help, you would use Variables. I’ll discuss how to create and use variables in Doc-To-Help in a minute, but I did want to note that determining what information to “chunk” into variables is the most time-consuming part of the process and takes a bit of up-front planning and design. Once you have finished planning, the creation process is simple.

To get started, take a look at your content and determine what pieces are used over and over. Some common software documentation examples:

Product Names
Field/checkbox/other UI definitions
Product descriptions
Terminology definitions

After you’ve sorted out what content you can reuse, create a list of everything that needs to be “greened.” You can then determine what type of variable each will need.

For very short pieces of content, use Text Variables. These are great for things like product names, because if the name changes at the last minute, updating is easy.

For longer chunks that may require formatting, Rich Content Variables are the way to go. They are ideal for definitions that are used repeatedly, and also for lesser used, but volatile information, such as product descriptions.

Once you have determined what you will reuse and how, you can get started chunking. You probably won’t have to do too much writing, because the material already exists. Some rewriting to merge like information may be in order. This recycling exercise will give you and your team the opportunity to update information that has not been reviewed in a while. So you’ll be increasing efficiency, and improving content at the same time.

Now to creation. Before you begin, think about naming conventions. It’s important to give Variables meaningful names, and when creating Rich Content Variables, make sure to divide your Variables into different documents that are also well-titled.

To create a Text Variable:

Open the Variables window (On the Project tab of Doc-To-Help, click the Variables toolbar button. )
In the Text Variables area, click on the Add New Variable toolbar button. An editable field named "New Variable" will appear in the Name column.
Enter a name for the variable, then double-click "Variable text" in the Text column to enter the text (one word or more).
If you’d like, you can assign one or more conditions to a Variable, so that it is only used in certain outputs.

To create a Rich Content Variable:

Open the Variables window.
In the Rich Content Variable area, click on the Create New Document button. Choose XHTML, HTML, or Word Document from the drop-down list. The Save New Document As dialog box will open. Enter the document Name and click Save to add it to your project.
Double-click on the document name in the Variables window to open it. The Variables document will display a table with two columns.
Enter variable name in the column on the left (avoid spaces), and the variable content in the column on the right. Apply styles as desired, including conditions.
Save the document.

Using Variables is easy … to insert variables in documents:

At the appropriate place in your source document, select the text that will be replaced by a variable and click the Variable button. Choose the proper variable from the list in the Variable dialog box. It is a good best practice to use the variable name as the placeholder text.

(In Microsoft® Word, Microsoft® FrontPage®, and Adobe® Dreamweaver® documents the Variable button is located on the Doc-To-Help tab or toolbar. In the XHTML Editor window, the Variable button can be found on the Insert tab.)

For more on Variables, see Creating Variables.

For more on Conditions, see Utilizing Conditions.

After you have created and are using your Variables, make sure to document your process and your variable naming conventions so that any new content is authored “green.”

Have fun creating “content that survives” with Variables.

What you can do with the Doc-To-Help Ribbon in Word

2009-07-02T16:04:00Z

This is the final of a three part series called "How do you like to write?" This post focuses on the Doc-To-Help ribbon in Microsoft® Word.

This ribbon (or toolbar, depending on your version of Word) appears in all Word documents that are included in your Doc-To-Help project. It allows you to create links, mark text as conditional, add variables, and more -- right within your Word document.

These features are useful for many reasons:

Creating navigation (Link button)
Customizing output (Conditional Text button)
Reusing content in multiple places (Variables button)
Adding index entries (Keyword button)
Other handy options, such as inserting a Flash movie, creating an image map for a graphic, adding a term to the Glossary, adding margin notes, are all here.

You may not need all of these features for your project, but you'll find many of them extremely useful for creating a robust project – while never leaving your writing workflow.

And, once again, you are writing a book, but still generating individual topics that transform into both logical Help and Manual output. And those same topics can be used in multiple Targets to create as many variations as you need.

Tips for Writing a Book, But Generating Logical Help

2009-07-02T15:44:00Z

In my last post (How do you like to write?) I discussed how Doc-To-Help makes it simple for you to write a book, chapter by chapter — and still output high-quality, feature-rich, *logical* Help and web output, as well as attractive manual output. In this post; a few writing tips...

If you follow certain guidelines when you are writing, the online output generated from your Word Documents will be logical and consistent, while not compromising your writing flow.

If you are writing software documentation, standardize on a consistent heading (such as “Using the… Screen”) which makes sense in both the book and help. Since your heading will become a topic in online outputs, also design a consistent structure for each topic that you will later map to Help buttons*. For example:

Title
Introduction
How to access the screen/dialog
Task(s)

Be sure to cover all the main points in under one heading, so that that a single topic will work for each dialog box.

Standardize on one (at most two) Heading styles that Help button topics will map to. It can be confusing to the user if multiple styles appear from Help buttons.
Never use the word “chapter” or any other word specific to books. (For example, “page” “topic” “help system” “manual”) “Section” is a good substitute.
Use “See *Insert Link*” rather than “See below,” “See above,” etc.

* This mapping is done using context IDs. See Implementing Context Sensitive Help.

Next time ... The Doc-To-Help toolbar in Word.

How do you like to write?

2009-07-02T13:36:00Z

With music blaring on your iPod? In a quiet corner? Actually, that's not where I'm going with this (although I admit I don't write and listen to music at the same time). I'm talking about something a little more fundamental. Do you like to write in a traditional narrative format?

If so, Doc-To-Help makes it simple for you to write a book, chapter by chapter — and still output high-quality, feature-rich, *logical* Help and web output, as well as attractive manual output.

And if you'd prefer to write discrete content chunks, you can do that in Doc-To-Help also using the built in XHTML Editor or an HTML editor (such as Adobe^® Dreamweaver^® or Microsoft^® FrontPage^®). You can even combine different types of documents in the same project. More on this in a future blog post.

But back to writing preferences … With Doc-To-Help, you can work in Microsoft^® Word, writing in an organic way, and Doc-To-Help takes care of the rest. You can write a book that flows, but transforms into logical Help topics. And you don't need to create separate topics – because Doc-To-Help creates them for you.

Writing in Word, Creating Help and Manuals Automatically

How does this happen? First of all, Doc-To-Help automatically breaks your Microsoft Word documents into individual topics based on Heading styles. It then uses the order of those topics to automatically structure the navigation of online outputs. If your documents have logical structure, so will your Help and web output, right out of the box.

Here's an example:

You write a chapter and apply the Heading 1 style to the chapter name. To the name of each section under that chapter, you apply the Heading 2 style. Each chapter can be a single Word document, or you can keep multiple chapters in the same Word document. Just use the Heading 1 style to designate the start of a new chapter.

By design, Doc-To-Help does the following when you build your output (manual, Help, or web output): Heading 1’s in your Word Documents automatically become parent topics, and all of the Heading 2’s under them become subtopics. This can be illustrated by looking at the automatic Table of Contents generated by Doc-To-Help. The automatic Table of Contents for both online Help and manuals is generated based on the structure of your documents, and their order in the Doc-To-Help Documents Pane.

Note that Heading 1's with no Heading 2's under them become "standalone" topics in the TOC. (You can customize the automatically generated TOC if you would like.)

Your online Help and Manual TOCs will be appropriate for each format.

Parent topics (Heading 1's) automatically include “See Also” links to their subtopics (Heading 2's) in online outputs. You can add additional "See Also" links manually, and the introductory text (More:) can be changed and its style customized.

There are a few other ways Doc-To-Help automates a "book" workflow:

· Links to other topics (created in Word using the Link button on the Doc-To-Help toolbar or ribbon) will automatically become cross-references (with page numbers) in your printed manual, while they will become hyperlinks in online outputs. You don't need to use Word's cross-reference feature to get both.

· Margin notes in your Word Documents automatically become pop-ups in online Help or web output.

And … Doc-To-Help automatically generates the Title Page, Table of Contents, and Index for printed manuals, so you don’t have to. It also adds footers. You don't need to use Word's features to create them. Just write and then build your Manual Target.

Next posts: Tips for Logical Help and the Doc-To-Help Toolbar

Until next time ...

Upcoming Talks on User Assistance

2009-03-02T19:41:00Z

Just a quick laundry list of my upcoming talks about User Assistance ... hope to see you at one (or more) of these events!

DocTrain West March 17-20 http://www.doctrain.com/west/

WritersUA March 29 - April 1 http://www.writersua.com/

Embedding Dynamically Updated Help into the User Interface Using a Dedicated Help Pane and Custom Control (Peer Showcase)

Society for Technical Communication (STC) Summit May 3 - 6 http://conference.stc.org/

Designing and Implementing Embedded, Dynamic User Assistance

Be sure to visit the ComponentOne Doc-To-Help booths at WritersUA and STC. In fact, if you are attending WritersUA, check out Doc-To-Help Day.

See you soon!

New Doc-To-Help Articles on DynamicHelp and more ...

2008-12-05T20:05:00Z

I've recently written three new articles that you may find helpful and posted them to our knowledgebase, HelpCentral. HelpCentral also has videos, FAQs, and other helpful information. Here is a quick article overview ...

If you would like to include embedded Help with your product, but couldn't because of the time and complexity involved, you may find the ComponentOne DynamicHelp control the solution you have been looking for. This control can be incorporated into the user interface of any application developed in Microsoft Visual Studio.NET, and the mapping of the interface to the Help file can be completely managed by the Information Development team -- no Context IDs needed (but you can use them if you'd like).
See Creating Embedded Help with the ComponentOne DynamicHelp control
One of the coolest features of Doc-To-Help is the automatically-generated “blue buttons” (AKA "Auto Subtopic Links") that appear at the bottom of Help topics. This article explains how to edit the Heading text, button graphic, and link text to your liking.
See Changing the Look of Auto Subtopic Links
You can change the look of your Help "skin" (or Theme) in Doc-To-Help with the Theme Designer. This article explains how to swap out the default logo (as well as its link and pop-up text) in a Theme.
See Changing the Doc-To-Help Logo on a NetHelp Target

Happy Holidays and Enjoy!

A few of my favorite (web) things

2008-07-02T14:07:00Z

It has finally stopped raining in Pittsburgh (for the moment) so I'm going to blog while the sun shines.

I love the 'Burgh, but it does rain quite a bit in June. We have a large arts festival -- the Three Rivers Arts Festival -- that coincides with the rain every year. But it all seems to work out.

So ... here are a few of my favorite (web) things ...

You can build your own fonts (and share them) with FontStruct http://fontstruct.fontshop.com/ (I read about this @ http://www.slate.com/id/2192535/)
The Duck Island Greeking Machine generates greeked text in seven "languages" (Classical Latin, Hillbilly, Marketing, The Matrix, Metropolitan, Pseudo German, and Techno Babble). Very handy. http://www.duckisland.com/greekmachine.asp
If you need to map colors for different outputs, the Tridesign PMS/RGB/Hex color (actually colour) chart is very useful. http://www.tridesign.com.au/index-tess1.php?ItemNo=2055

While on the subject of the web -- I highly recommend Janice (Ginny) Redish's new book Letting Go of the Words -- Writing Web Contents that Works. Lots of great information and solid examples. I have post-it notes all over my copy.

Lastly, an interesting article from slate.com about how we read online http://www.slate.com/id/2193552/ (Jakob Nielsen is referenced).

More later

Dynamic Help: I’ve got it and you can have it too

2008-05-22T21:01:00Z

I’ve worked on a number of software products, and there were several that were ideal candidates for dynamically updating, embedded help – but since that sort of effort is usually software developer-intensive, I was never able to make it happen (not for lack of trying by myself and some wonderful software developers).

The wait is over; and convergence was the answer. Doc-To-Help is developed by ComponentOne; ComponentOne develops components software developers use to streamline Visual Studio development. The C1 DynamicHelp for Winforms control was born.Short tour: this control can easily be dropped into the main window of your app, as well as in dialog boxes. Once the software developer has configured it, that’s all they have to do. Mapping a compiled Help file to the user interface is the information developer’s job, because the control includes a mapping interface. Once you’ve mapped, the end user has help that updates automatically as they navigate the interface. The right help at the right time. You can see it in action in Doc-To-Help 2008 (download a trial version at http://www.componentone.com/Products/DocToHelp.aspx) If you are attending the STC Annual Conference in Philadelphia next week, you can see it there at the Doc-To-Help booth. The Dynamic Help control will be available in June. I’ll be talking about the project itself (among other things) at DocTrain East this fall. See http://www.doctrain.com/east/program_detail/all_around_user_assistance_delivering_layers_of_information_efficiently/ for more information on that.

"Camp" on the Road: STC Annual Conference in 10 Days

2008-05-22T14:21:00Z

Since I need to play a bit of catch up; a few updates and thoughts...

Can't think of a better way to kick off summer camp than the STC Summit in Philly. (Full disclosure: I'm currently an STC Director At Large, but I've been attending the Annual Conference for years.) Hope to see you there.

Earlier this month I attended DocTrain West in Vancouver. I did a talk titled "Documentation Planning and Library Design in a Web 2.0 World." I'll be posting more on this subject later. While I was there Tom Johnson interviewed me for a podcast that he will be posting on his "I'd Rather Be Writing" blog. Looking forward to hearing it.

Great Web 2.0 read (albeit from a marketing perspective) -- "Groundswell: Winning in a World Transformed by Social Technologies" by Li and Bernoff.

More later!

Welcome to Technical Communication Camp!

2007-10-05T20:33:00Z

There are a number of tech comm blogs out there (the ones I keep up with are listed on my blogroll) but the cool thing is that they are all different, with different themes, perspective, and – probably most importantly – tone.

Today, I’m adding my voice to the mix.

My blog’s name, Technical Communication Camp, refers to the fact that we are always learning – and that we should try to have a bit of fun along the way.

With that in mind, I plan to keep you up-to-date on what is going on in the world of technical communication, handy tips and tricks, and maybe even try my hand at podcasting.

Smores anyone? :-)