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.
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/).
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.
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.
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!
- 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.
- http://www.marshalldocumentationservices.com/ - Ed Marshall’s website, which has a list of upcoming workshops and presentations on this field. I’ve barely scratched the surface of what was taught. You can also follow him on Twitter @EdMarshall.
- http://groups.yahoo.com/group/svcstcapi - A Yahoo group for the STC’s API SIG.
- http://www.linkedin.com/groups/API-Documentation-3709151? - A LinkedIn group for API Documentation, started by my fellow Seneca College Technical Communication program alumnus.
- http://www.stc.org/ - STC Conferences and Workshops.
- Books written on APIs, learning to program, and API and SDK documentation. Ed recommended Manual Gordon’s API workbooks (http://www.thirdwavestudios.com/gg/api_workbook.html) and “Documenting APIs Writing Developer Documentation for Java™ APIs and SDKs” by James F. Bisso and Victoria Maki, currently sold here (http://www.bitzone.com/).
- https://www.coursera.org and http://www.codecademy.com/ - For learning how to code and sample exercises.