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

organizing 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.

standardizing 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.

obscuring 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.

what skills are demonstrated?

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.

interviewing tool

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.

publishing

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.