API Introduction

A good introduction helps the developer understand what is required to use the API. It states what is required, i.e. software, and encourages the reader to learn more. It usually includes points of reference, i.e. where to get started. Introductions help the developer to understand why an API was written. It also describes a few objectives or goals. It may announce new features that have been added.

Preparing a Technical Writing Portfolio

Organize writing samples

I organized my writing samples according to the company they were created. I created a nice cover pages to introduce myself and each company.

Standardize document format

I have written many documents in different mediums, i.e wiki, Word, Framemaker and hard copy. I decided to convert all of the writing samples into Word to make it consistent and easier to manage. If I wanted to show the document as it appeared in its original context, I took screen shots and then mounted the image inside of the Word document. The samples take a small hit in clarity but it achieves the desired end result.

Obscure confidential information

Not all information written in a document is “confidential”. To overcome the issue, I reviewed the document and obscured key information points such as IP addresses or key information captured in diagrams. Since I spent so much time gathering information and preparing the information, I think I understand what was confidential and what was not. The point is that a client can see how the document was organized, images placed and how information was written.

Skills

Each document sample should demonstrate the use of your skills.  Each document represents hours of effort and care. In the end, when a client opens up the document, it is important to realize what the document says about my skills.

Do I have to include the entire document? I believe the Sample should be just enough to get the point across. It is like a Reader’s Digest of what you did and should provide enough information for the client to understand. Since it is likely they won’t read a 100 page user manual–choose a chapter.

Visual aid

I also use a portfolio as a sales presentation. When in an interview, I can open up the document to support answers to questions. You can point out how you solved a particular problem and how it was done.

Publish

I created a Word file with the writing samples for each company. I kept the files separated by company to make it easier to assemble a final portfolio. package. I opened a new Word document and added document samples from each company according to a skill set that I wanted to emphasize. I generated the table of contents and then printed it as PDF. Now I can upload this for use on LinkedIn using their new slide show. I can create several different portfolios organized to show a specific skill set.

What are Documentation Services worth?

Move Networks invested a huge sum of money to upgrade hardware and software to scale up support for live video streaming, earlier this year. Move streamed HD live content for Channel Bee, a London-based Internet television station and for the broadcast of NFL football games for NeuLion to thousands of simultaneous users. Move announced that it was restructuring and changing its corporate strategy.

It was explained to us that the end-to-end service was going to be phased out. The new strategy is to license the technology to partner resellers such as iStreamPlanet. These partners would then resell Move’s technology. I was a little surprised when I and another writer were told we didn’t have a role in the under the new strategy. I asked the question, “If you are going to license out the technology, won’t your partners need some API documentation?” All I got in response was, “good question”. I believe someone thinks that developers are going to create the documentation.

However, in my experience, developers are always under tremendous pressure to develop new features and fix bugs without having to answer customer questions. This happens because there isn’t any documentation! So a cycle begins where developers are pulled away from their development efforts. The same questions are asked and someone says, “why doesn’t someone write this down?”

In addition, when no one is focused on maintaining documentation information becomes tribal knowledge. The information inevitably becomes corrupted and confusion ensues. A few may create documents but this usually leads to conflicting document versions. In a crisis, a customer wants to trust that the documentation received can be relied upon but it is usually too late. The customer ends up feeling frustrated and considers other vendors. 

A customer service manager (CSM) is working to resolve a customer’s problem. The aspect ratio is being rendered incorrectly. Sometimes a developer is contacted. This interrupts his coding and makes it harder for him to fix bugs and add a feature. It turns out that the answer to that question is in a user manual that was published and made available for customer use. It contains an easy to follow procedure that enables Publishers to submit their content that is correctly ingested and rendered for viewing. Developers can focus on their work and customers are not left feeling frustrated. 

I have written naming scheme specifications,  Network Operations architecture that explains how video content is ingested and delivered to millions of simulataneous users and developer guides.

Move Networks Silverlight Developer Guide

Microsoft’s Silverlight is a web application platform that integrates multimedia and interactive content. A Silverlight solution works in conjunction with XAML and is scriptable with JavaScript. Silverlight applications are developed using Visual Studio and the .NET framework.

My assignment is to write a developer guide for implementing a Move Player in a Silverlight application. I downloaded and installed Visual Web Developer Express with SP1 and then installed the Silverlight Tools for Visual Studio 2008 SP1 add-on.  I’m using Silverlight’s built-in WPF UI framework to create the UI. To get started quickly, I read Scott Gu’s Silverlight Tutorial and completed lessons 1 and 2. 

I interviewed Richard, a Move Developer, who gave me a whirlwind tour of how to build a Silverlight application and use the Move Silverlight SDK to add a Move Player and controls. I used Wink to capture screen shots during our interview. After I got back to my desk, I edited frames and added comments to key frames. I will use this saved session as a frame of reference as I repeat the development process on my own.

I organized the document to introduce Move Player and Silverlight in context of developing a web application that plays Move streaming video content. I start with a brief introduction about the Move Player and Silverlight. 

Silverlight and Move Player are browser plug-ins. Silverlight is a platform for developing rich internet applications and Move Player delivers HD quality video over the internet with virtually no buffering.

This tutorial provides a quick introduction to implementing a player in a Silverlight web application. We will build a Silverlight application that contains a Move player, add controls and play a sample movie.

They are both web browser plug-ins and the Silverlight development environment requires a few configuration steps to get started. The SDK is actually a Silverlight project with some classes that makes it easier to work with the Move Player.

Writing Usable Documentation

I was asked to reorganized the help documentation again. The service is constantly evolving and it is difficult to keep up with what is needed. As I research how a process works, I have ended up serving in a testing role. I have written many bug reports that have led to many improvements in the ContractPal service.

I have to continually think about the end user’s perspective. I test my own documentation, following each topic carefully to make sure instructions are clear and understandable. Can the user create a Pal and successfully implement it in their application? The answer is usually delayed because I’m still waiting for a feature to be implemented or a  bug to be fixed.

Learning Java Head First

I purchased a copy of Head First Design Patterns. I read the first few pages and I was impressed by how accessible the content is, I actually remember what I read and I want to keep reading more.

Making information accessible is the first and most important step in good technical documentation. I love adding simple and easy to read illustrations to my own documents. A diagram, line drawing or even a simple model that shows how things connect together in context make a big difference.

Based on what I read, I ordered Head First Java, 2nd edition and Head First Object-Oriented Analysis and Design: A Brain Friendly Guide to OOA&D.  I didn’t intend to go on a book buying spree but I felt like it was the right thing to do.

Whizlab SCJP 5.0 Preparation

I purchased a license for Whizlab’s SCJP 5.0 exam simulator. The simulator helps with exam preparation by presenting questions that mimic the SCJP test conditions. Questions are presented with a time limit and afterwards you can review each test question to understand the correct answer.

I took the diagnostic exam in two parts and I was overwhelmed. The test is intimidating. I learned that the diagnostic is actually harder then the real test. I believe it is a good investment. The exam simulation motivated me to study harder. It infused me with more enthusiasm for learning the Java API.

Writing PHP Script

I accepted a stretch goal to create a needs assesment form yesterday. It started with my inquiry into how a user would create an ContractPal Enterprise account. The new account creation process is still a bit convoluted. As we discussed possible solutions, Brad asked if I could create an “opportunity assessment” page and add it to the company web site.

We decided the requirements would be a needs assesment form and contact information, e.g. how many transactions in a month or how much time is required to close a transaction. The submitted form is forwarded to his email address. He can then follow up with a phone call or email.

We are using MODx, a content management system. I starting reading the help documentation. I found a PHP code sample called ‘Web Lead’. It provides a simple form a visitor can fill out. Now, I need to add additional questions next to radio buttons and figure out how to send the form via email. I visited W3Schools to get started learning more about PHP. It turns out that it is very similar to JavaScript and the ContractPal RhinoScript I have used for developing Pals.

Java Language Specification

I found some interesting blogs today and one of them led me to discover the Java Language Specification. I am very interested in reading about API development. I was surprised at how much I enjoyed reading this specification. It reveals many insights into whys and hows for creating Java. I quote from the introduction, “It is intended to be a production language, not a research language, and so, as C. A. R.
Hoare suggested in his classic paper on language design, the design has avoided including new and untested features.” The book was available for download as a pdf and contains 684 pages.

Yellow Belt Passed

I passed the Java SE basic test today. I persevered and succeeded. I attempted the test about 6 times before I passed it. Onward and upward! Now I will prepare to challenge Sensai for my orange belt; Namaste.

I studied the Sun Javadocs collections today. There are 9 different interfaces for handling collections of objects. I continue to study Java Certification chapter 3 (Sierra Bates).