Stack Overflow Introduces Crowdsourced Documentation

creative-desk-pens-school

A couple of weeks ago, a coworker sent a link to our company’s software documentation team.

“Thought this might be of interest,” he said.

It seemed both offhanded and ominous. When I clicked the link, the blog post’s headline definitely gave me pause: Introducing Stack Overflow Documentation Beta.

Stack Overflow, the eminently popular discussion site where programmers can ask and answer coding questions, is staking out new territory. It intends to be the go-to site for technical documentation. Crowdsourced technical documentation.

As Stack Overflow sees it, documentation “by most appearances stopped improving in 1996. We think, together, we can make it a lot better.” So at Stack Overflow Documentation, people can create and publish documentation that will be continually buffed and polished by the developer community. As on the Q&A site, quality answers can be up-voted, and contributors can earn reputation points and badges.

Continue reading

What is API Documentation?

Written by Peter Gruenbaum

API documentation is a fast-growing segment of technical writing. API stands for Application Programming Interface, and it’s the way that software systems communicate with each other. What sets it apart from other types of documentation is that you are writing for an audience of software developers. APIs provide certain functionality, and software developers need to understand how the APIs work in order to build applications that use them.

There are several types of APIs, including programming APIs, web APIs, and hardware APIs. This article will discuss the two most common types, which are programming and web APIs.

Do you need to know how to write code in order to document APIs? There isn’t a simple answer to that question. For some types of APIs, you should know programming fairly well. For other types, it may not be required, but it is often useful.

Programming APIs

A programming API (also called a “client library” or SDK, for Software Development Kit) is a set of software functionality that runs on a device, such as a smartphone, tablet, desktop, or server. For example, a software developer creating an iPhone app would use the iOS SDK. Let’s say that a developer wanted to be able to pop up a window that asked a question and prompted the user to tap “OK” or “Cancel”. API documentation tells the developer what code is required to do that action. It may involve several steps, such as first creating the dialog, then displaying it, and then reacting to the choice that the user made. The developer needs to know how to specify the message, how to specify what buttons to display, and how to find out what button the user tapped.

API documentation writers definitely need to understand some level of programming in order to document programming APIs, but how much you need to know will vary. The documentation for the iOS example I gave above (UIAlertController) requires a great deal of knowledge about iOS programming in order to understand it. However, many programming APIs are a lot simpler, and require only that you have a good understanding of object-oriented programming languages like Java. If you write documentation without having that solid understanding, then you may write something that is not completely accurate, and developers will no longer trust the documentation.

Web APIs

A web API defines the communication between a client device and a server over the web. Web APIs are a relatively new phenomenon in the software industry, but several recent technology trends (mobile devices, the internet of things, and big data) have made them extremely popular. The site ProgrammableWeb contains a directory of publicly-available web APIs, and they analyze the data and look for trends. As you can see in the graph below, the number of these APIs have grown exponentially. And these are just the public APIs — people in the industry say that there are 10 times more web APIs that are available only internally or to partners.

Source: ProgrammableWeb

Source: ProgrammableWeb

 

There is a debate in the API documentation community as to whether writers need to know how to program in order to document web APIs. Understanding programming can give you a good perspective on how web APIs are used. That said, web APIs are not really about programming as much as they are about data. The most important thing you need to understand to document web APIs is how to document structured data, such as XML (eXtensible Markup Language) and JSON (JavaScript Object Notation).

What API Documentation Should Cover

Like any kind of technical writing, API documentation needs to provide both overview material to orient the reader, and reference material to provide specific information on how to accomplish tasks. Here are sections that are common in API documentation:

• Overview — what the API does and why you should use it
• Getting Started — a short series of steps to quickly get to the first use of the API
• Architecture — for programming APIs, how the various pieces fit together
• Authentication — for web APIs, how security is handled
• Tutorials — step-by-step instructions that leads the reader through how to accomplish common tasks
• Reference — detailed information on what each piece of the API does

How to Learn More

Several resources are available to learn more about API documentation. They include:

STC webinars by Sarah Maddox, Ed Marshall, Joe Malin, and others

Workshops by Marshall Documentation Consulting

Online courses by SDK Bridge

 

 

 

Why Should I Care About DITA?

DITA-sprout

Source: TechWhirl

DITA, Darwin Information Typing Architecture, is an XML-based standard that is used primarily for technical documentation and increasingly for other types of documentation too.

If you’re not applying DITA as your documentation standard, then you’re working much more slowly and inefficiently than you ought to.

DITA Saves Time

If you and your writers are forever mucking around with Word style, templates, footers and headers and generally wasting your time on not creating content, then you should seriously consider moving to DITA.

DITA separates content from formatting so that writers write; they don’t format. Formatting is applied automatically and consistently as part of the publishing process.

That extra time gained from authoring in DITA doesn’t mean that you can reduce the writer headcount, because the extra time should be spent focusing on writing the right information, the information the user really wants and needs…which leads to the next reason you should care about DITA: increased quality.

DITA Introduces Quality and Consistency

DITA gives writers a clear, repeatable, yet customizable model to write from. For example, DITA requires every topic must have a title; pre-requisite information for performing a task always precedes the context of a task (and the steps); and a task result always follows the steps.

With DITA, writers have (just) enough structure to consistently write according to best practices, like telling people what they need to have or know before telling them the first step. It’s not uncommon to find a step that surprises the reader with information they should have known before they even started the task. That sort of information is now clearly placed before the steps begin.

Writing using DITA leads to clear, consistent information. In fact, most writers take this one step further and start to identify real user goals and then write to those goals instead of writing based on features. This further increases the quality and usability of the content.

At the same time, formatting discrepancies disappear because formatting is applied centrally and programmatically at publishing time, rather than randomly throughout the content creation process.

DITA Increases Usability

DITA introduces a shift—from chapter- or book-based writing to topic-based writing, where each chunk of information is clear and complete on its own. Furthermore, each chunk, or topic, has a clear purpose. The core of DITA includes different topic types, each written to fulfill a specific users’ goal: concept to explain, task to instruct, reference to inform.

Separating content into discrete, highly usable but clear topics makes them more findable. Users can navigate right to the information they need, read just the pertinent information (because the rest is there, a click or swipe away), and then go about their day.

Happy users make really good customers and no one is happier than the user who finds exactly what they need in the documentation.

DITA Opens Up the Door to Publishing Options 

By having content in XML, you’re freed from the constraints of one particular output format, like HTML or PDF. You are limited only by your technical skills at transforming XML into any and all other outputs that you need (and that your users need).

From ePub to Excel or PDF to PowerPoint, creating the outputs you choose is a matter of mastering transform languages (or hiring someone who can create what you need using those transform languages). Your outputs are entirely configurable, looking and behaving exactly as needed.

It gets trickier when you try to integrate DITA outputs with other tools, like publishing through WordPress or Drupal. However, it’s usually a matter of time and money rather than an impossibility.

DITA Saves Money 

By not messing around with formatting and by having a clear standard to write and reuse content, writers can write faster. When content is in DITA, it becomes an object that can be used anywhere it’s needed. No more copy/paste. This means savings when you’re writing new content, updating existing content, or assembling new product documentation.

Translation also becomes a major source of savings in a DITA environment. Instead of translating complete documents over and over, you only need to translate the specific content that has changed. Organizations regularly see a savings of 50% or more when they translate DITA content rather than Word, FrameMaker, or InDesign.

Summary 

These are just the high-level advantages of DITA. We haven’t even touched on the ability to tailor content to a particular type of user, make content even more findable through faceted search, or make reviews faster and easier (and on time!).

If you care about the quality of your technical content, you should care about DITA, and start planning how to move your documentation to a new level.

Have something to add? Please share it in the comments.