Importing Code Samples with DITA (or How to Avoid Serious Headaches)

So now we know that good API documentation must include code samples. But if we want our users to base their code on our examples, we must make sure that they are valid and always up-to-date.

In general, the code samples are simply copied from the developers’ source files and pasted into the documentation. If the source code is updated after the documentation is released–for example, if a new mandatory parameter is added to the API–then the documentation must also be updated. Manually checking that all the code samples are still valid may be possible if the documentation is short and simple, but that is rarely the case when documenting APIs. Updating code samples manually can quickly become unmanageable (not to mention be the source of a serious headache, as I unfortunately had the chance to experience recently).

To solve this issue, the code samples in the documentation should be linked to the developers’ source files so that any change to the code will be reflected automatically in the documentation. In DITA, this can be done with the <coderef> element, which is available inside a <codeblock> element.

For example, consider the following source file:
C:\SVN_Checkout\product_x\src\samples\HelloWorld.java

class HelloWorld {
 public static void main(String[] args)
 {
 System.out.println("Hello World!");
 }
}

In the DITA XML file, the reference to this sample would be coded as follows:

<p>The following code shows the infamous "Hello World!" Java class:</p>
<codeblock>
  <coderef href="..\..\SVN_Checkout\product_x\src\samples\HelloWorld.java"/>
</codeblock>

When transforming the DITA file, the output would be similar to the following:

Some guidelines when importing code samples:

• The imported source files should be short and sweet; importing a Java class that goes over four or five pages in the documentation is not very useful (or readable).
• The source files should be well commented and include white space for readability.
• The documentation should be stored with the software, using a control management system, so that the paths to the source files are always valid.

One disadvantage of using <coderef> is that the source code cannot be formatted once it’s imported, so for languages with amazingly long class names (like Java!), it can be downright ugly. Another disadvantage is that <coderef> imports the complete source file, which is not always optimal. Sometimes I only want to include short sections from the source file. Fortunately, this can also be done in DITA, but it’s a bit more complicated.

Including code snippets
To include code snippets in a document, one solution is to create a script that extracts from the source files only the sections that are of interest to the documentation. The script looks for keywords in the comments, indicating the beginning and end of the code samples, along with an ID in a <ph> element uniquely identifying the sample. The output of the script is a DITA file that contains all the code snippets with their IDs.

For example, assuming that the script looks for the DITA_START and DITA_END keywords, a code snippet could be coded in the Java file as follows:

/** DITA_START:<ph id="helloworld_example"> **/
class HelloWorld {
 public static void main(String[] args)
 {
 System.out.println("Hello World!");
 }
}
/** DITA_END:</ph> **/

Running the script generates a valid DITA file (for example, dynamic_code_sample_library.dita) that contains the code snippet:

<codeblock>
 <ph id="helloworld_example">
   class HelloWorld {
     public static void main(String[] args)
     {
     System.out.println("Hello World!");
     }
  }
 </ph>
</codeblock>

 <p>The following code shows the infamous "Hello World!" Java class:</p>
  <codeblock>
    <xref conkeyref="dynamic_code_sample_library/helloworld_example"/>
  </codeblock>

With this solution, I run the script to make sure that the code snippets are up-to-date, I generate my DITA output, and voilà! Well, that’s the plan anyway. I’m currently working on the script, so the headache occurs at the beginning of the project ;-) But I’m having fun and know that it will be worthwhile in the long run!

For more information on creating good samples

Get Technical, Have Fun, and Become a Coding Ninja

As technical writers, we must constantly develop our technical skills to keep up with ever-evolving technologies. While reading books and technical articles can introduce us to new topics, there is nothing like hands-on training to fully grasp a subject. As a permanent employee, I could get that training through seminars or conferences paid by the company, but as a consultant I find these courses very expensive.

But there’s hope. I recently came across a fun way to learn new programming languages. And it’s free.

Codecademy is a new startup that offers free, web-based, interactive programming courses for the non-technical. Their objective is to turn non-programmers into “coding ninjas.” That may not be what we all want, but the world does need more techie tech writers.

If you’ve never programmed before, the first Codecademy course–Getting Started with Programming–teaches you the basic principles and concepts of programming, such as if statements and while loops. This class is also a pre-requisite for the other courses.

What makes Codecademy different from other web tutorials I’ve tried is that it’s actually fun. The interface is simple and beautiful and the instructions are clear and well written (although some sections might benefit from a little editing). Every lesson includes hands-on exercises that you must complete to move on (no cheating possible :-). Short quizzes help you determine how you’ve assimilated a topic, and you can track your progress through badges and scores.

Codecademy is not only a great way to get more technical, it’s also training documentation at its best.

I’m now learning JavaScript, which is the only course currently available, but Codecademy is working on developing courses for other programming languages, including Python and Ruby.

I can’t wait :)

Error Messages and the Technical Writer

I once had a very interesting discussion with an engineering manager. We were reviewing upcoming projects and trying to determine the documentation that would be required. Talking about logs and error messages, I told him that, in an ideal world, they should be self-contained and so obvious that they would not need to be documented. He smiled and said: “But then, wouldn’t you be putting yourself out of work?”

No. Quite the contrary, actually.

Being a technical writer involves much more than writing the install, admin, and user guides that go with a product. Every user interaction provides an opportunity to help our readers work with our products. That is particularly the case with alarms, logs, and error messages, which provide information that they are generally very interested in.

Messages are usually written by developers, for whom writing is often not a strength nor an interest. They are written quickly–rarely with the user in mind–and almost never indicate what users should do about the problem they’ve encountered. Some messages are sometimes so cryptic that we end up writing developer-language-to-plain-English translation guides, which can be very frustrating to our users: They are stuck in a bad situation and get a message that is not very instructive, so they need to open a troubleshooting guide, find the error message, read the description and required action, and then go back to the interface.

Whenever possible, why not simply provide all this information directly in the alarm, message, or log? Obviously, some complex situations require a more detailed description and action plan, which cannot be provided in a few lines. But in many cases, this is a perfect opportunity to use our skills and work with development to write better messages. This can be achieved in a few ways:

• Through test plans: In my current mandate, we are using a test plan to document the error messages. For each test case, a column is added to the spreadsheet to specify the message that should be displayed in this situation. The developer uses this to code the text message.
• By attending development meetings: These meetings provide the perfect opportunity for us to be a user advocate. In a recent meeting, while discussing a particularly problematic situation, the product manager suggested to the developer that he should provide a detailed error message to the user. I’m pretty sure that I saw panic in the developer’s eyes for a brief moment, quickly replaced by relief when I volunteered to write the message. :)
• By editing the error messages directly: In many cases, the error messages are centralized in a file. We can then rewrite them as required.
• By working with the software and providing feedback: We sometimes wait until a product is stable to start documenting it. But working with very early versions is a great way to get to know the product and to start writing clear messages. Since the developers are still working on the product, it is easier for them to include our feedback than it can be when the product is close to completion.

The world is already full of rather wild error messages. Let’s aim to make life easier for our users :)

***

For a great article on writing meaningful error messages, see Jakob Nielsen’s Error Messages Guidelines.

Examples, Examples, Examples

One of the first rules you learn in creative writing classes is “show, don’t tell”. So instead of writing “The man was very nervous”, you write something like: “He could not stand still. He sat down, got up, then sat down again, always glancing at the clock.” Can this rule apply to technical writing? I think it can, in some ways.

I recently did a documentation satisfaction survey for a product targeted to developers and integrators. When asked what they’d like to see more of in the documentation, they often answered: examples. More code samples. More sample configuration files. More sample output. Examples allow readers to put everything together. They also provide a great way to get started without having to read pages of documentation. That is especially the case when documenting code. Sample code allows developers to get started by copying and pasting the example and then adapting it to their needs. They can then go through the more detailed API documentation to expand their code.

As technical writers, we’re not always in the best position to provide these examples, especially when documenting complex features. Our job is then to obtain this information from developers once we’ve identified the areas that would benefit from such examples. Because this requirement adds to their workload–especially for more detailed sample applications–they may not always be willing or available to provide them. However, we must convince them–or the project manager–that this information is essential. While requiring additional effort during the development phase, good examples will often save time in the long run since developers won’t have to provide as much support once the product is out.

Ideally, developing solid examples should be planned in advance (or, if working in Agile, added as a task in the story). These samples also need to be tested and provided in a format that lets users copy and paste easily. For example, in a previous project it was decided to include sample applications in Python, Java, and Perl. Each sample application was documented on a wiki, taking the reader through the steps required to create the application, as shown below:

The users could also download the source files and start editing them directly. The samples had been tested by the developers, but I also tested them again, going through the same process as a typical user (download, modify, compile, run) to make sure it ran smoothly. We received very positive feedback from end-users and planned to add more sample applications in the next release.

Obviously, strong technical information is essential, but complex topics and tasks will always benefit from solid, detailed examples. So maybe in technical writing the rule should be “show and tell”. As writers, we’re very good at telling, but maybe we need to show a bit more.