Home‎ > ‎Connect‎ > ‎Members' Blog‎ > ‎Reports from Community Events‎ > ‎

Review of Ed Marshall's workshop on APIs and SDKs / by Veronica Starovoit

Chances are, if you’re a technical communicator and have recently perused any job descriptions or community forums in this field, you’ve seen numerous references to API, SDK, and other developer documentation. This comes as no surprise, as this is an increasingly digital world and developers are the bread and butter of any company that produces software. This was one point Ed Marshall emphasized in his one-day workshop, “APIs and SDKs: Breaking Into and Succeeding in a Specialty Market”, in New York City. Ed said that developers should be reminded about how important they are and be supported in their work to produce the best tech possible. We technical writers can add sweetness to their field and make software more digestible.

What are APIs and SDKs?

As a simplified analogy, APIs (Application Programming Interfaces) and SDKs (Software Development Kits) are the software equivalent of building blocks. APIs provide a single building block that other software developers and companies can plug into, and use in their own products. Two examples of popular, well-documented APIs are produced by Google Earth (https://developers.google.com/earth/) and Twitter (https://dev.twitter.com/). SDKs provide a whole building block kit that users can customize and build what they want. Great examples of SDKs are produced by Microsoft (http://msdn.microsoft.com/dn369240#fbid=G1CN74bIus7) and Facebook (https://developers.facebook.com/docs/sdks/).

What Part of APIs and SDKs is Documentation?

Documentation is an important part of both of APIs and SDKs. Similar to what is provided for other end users, Technical writers create installation, administrator and reference guides to provide information on how each of these work. In addition, it is often necessary or helpful to provide instructions, code comments and even working code examples about how the blocks may be used. Ed Marshall, who has over 25 years experience in the field of technical writing, is a specialist in developer documentation. He is one of the only trainers on this topic.

Two industry-standard tools

Ed covered two industry-standard tools in his workshop for providing documentation – Doxygen and JavaDocs.

Doxygen

A powerful and free tool, Doxygen (http://www.stack.nl/~dimitri/doxygen/) supports developer documentation in C/C++, Java, Python, IDL (Interactive Data Language) and C#. Ed walked us through best practice information, example exercises, and documentation snippets to add to a sample codebase. For the seminar, we downloaded and used Microsoft’s HTML Help Workshop, (http://www.microsoft.com/en-us/download/details.aspx?id=21138) and generated our Doxygen documentation into it.

Javadoc

Another industry-standard tool Javadoc by Oracle, (http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html), was also covered. This tool is also free and used for documenting Java programs. To supplement this tool, we downloaded NetBeans (https://netbeans.org/), which is the equivalent to Flare/RoboHelp software for developers. It helps them organize and manage their coding. We created a project using the NetBeans environment similar to where developers do their work. We were able to add our own documentation to the environment and insert it straight into the Java codebase that developers would use during development. By working in the same source control setup and environment as developers, technical writers can see what code has been worked on and edit the documentation that goes with it, as needed. Watch out, though – we have to be sure not to break any code or builds with our own edits!

The Conclusion: Should You Go into Developer Documentation?

Ed Marshall’s seminar definitely covered this question, and I will share some of his considerations:
  • Developer documentation is more technical, risky and advanced than most end user work. There is a real shortage of talent in this field, and as a result, the pay is on average 30-40% more.
  • You will have to learn some code, but mainly to read and comment on it, not to be a programmer (although some jobs do ask you to build working code samples). Ed recommended C/C++, C#, and/or Java as some popular languages to start learning.
  • Some personality traits which will make you successful are: the ability to work well with and extract information from developers, a willingness to work with programmer types of tools, an ability to write geared for developers (that is, eliminate all fluff and even use sentence fragments when you know they’ll be scanning for one point), keep information complete and easy-to-find, and find your own tools and courses to keep up-to-date with this field, as it’s constantly growing and changing.
  • Break into the market by writing some example programs, or write some helpful developer documentation to aid with your own company’s APIs, SDKs, and codebase.

Additional Resources

Here are some additional resources to help you with your research:
Comments