O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

Survival Strategies: Building your first website for API documentation

733 visualizações

Publicada em

This presentation explores the challenges that building your first website for Application Programming Interface (API) documentation may present. It investigates how you can leverage minimal resources to create documentation that provides useful information to support the adoption of your API by third-party developers.

Publicada em: Software
  • Seja o primeiro a comentar

Survival Strategies: Building your first website for API documentation

  1. 1. Presented by Mary Linderman Andrei Essaoulov
  2. 2. Welcome  Introduce basic concepts underlying developer documentation.  Explore ways to develop your technical skills.  Discuss content and code samples to include in API documentation.  Explore how to choose tools for developing your website.  Investigate simple strategies for usability testing.  Discuss optimizing your website for searching.  Describe possible opportunities for automation. STC Summit 2015 Survival strategies: Building your first website for API documentation 2
  3. 3. Goals for this presentation  Offer a vocabulary for discussing API writing.  Supply key takeaways for building your first website.  Provide insights for the future development of your site. STC Summit 2015 Survival strategies: Building your first website for API documentation 3
  4. 4. What is an API?  API is an acronym for application programming interface.  Includes the tools used by third-party developers to build applications on an existing code base.  Public code used to reference functionality already implemented by an internal development team. STC Summit 2015 Survival strategies: Building your first website for API documentation 4
  5. 5. What is an SDK?  SDK is used to represent software development kit.  SDK includes the following tools:  Libraries containing the code referenced by third-party developers  Utilities used to facilitate implementing an application  Code samples illustrating how to use your API  Other resources STC Summit 2015 Survival strategies: Building your first website for API documentation 5
  6. 6. Object-oriented (OO) languages  OO programming languages includes C#, Java, C++, Objective-C, and other languages.  Models code on real-world or business entities.  Used to implement backend code that controls the functionality or features exposed in the API. STC Summit 2015 Survival strategies: Building your first website for API documentation 6
  7. 7. Example: API for a Tech Comm App  Includes a technical writer as a business entity.  Implements a class called TechWriter.  Add fields or properties to the class, such as name, current project, and work hours.  Add methods used to determine the behavior of a writer, such as outlining, writing, and proofreading. STC Summit 2015 Survival strategies: Building your first website for API documentation 7
  8. 8. Example: TechWriter STC Summit 2015 Survival strategies: Building your first website for API documentation 8 Business entity Technical writer TechWriter class Fields:  name  currentProject  workHours Methods:  Outlining  Writing  Proofreading
  9. 9. Working with an API A developer works with the API to perform these tasks:  Uses the class as a template to add multiple technical writers to the application. They are called instances.  Implements code that assigns tasks to these instances. STC Summit 2015 Survival strategies: Building your first website for API documentation 9
  10. 10. Working with an API API writer works with the API to document:  How to create these class instances  How to set their properties  How to use the methods that control their behavior STC Summit 2015 Survival strategies: Building your first website for API documentation 10
  11. 11. Example: TechWriter class STC Summit 2015 Survival strategies: Building your first website for API documentation 11 Sample source code for the TechWriter class
  12. 12. Business value of APIs  Provide a way for developers to make unique services or data available to customers.  Support custom applications or integrate functionality on a website to attract customers.  Generate significant revenue for company, as exemplified by Expedia, eBay, Twitter, and Google. STC Summit 2015 Survival strategies: Building your first website for API documentation 12
  13. 13. Business value of APIs STC Summit 2015 Survival strategies: Building your first website for API documentation 13
  14. 14. Adoption strategy - API writer  Understand your organization’s adoption strategy to facilitate adoption.  Works with product management to identify the significant features of the API.  Use adoption goals as context to frame the presentation of the API’s technical components.  Develop information about how to use the API for building applications or accessing services. STC Summit 2015 Survival strategies: Building your first website for API documentation 14
  15. 15. Adoption strategy - resources  Use the adoption strategy to identify required writing resources.  Request developer time for reviewing content, writing code samples, and creating sample applications.  Identify tools, additional writers, or other resources needed for the documentation. STC Summit 2015 Survival strategies: Building your first website for API documentation 15
  16. 16. Ramp up your technical skills  Identify the programming language and other technologies used to build the API.  Use this information for these purposes:  To enhance your technical vocabulary.  To develop your ability to read code samples.  To improve interactions with development teams.  To produce well-written documentation. STC Summit 2015 Survival strategies: Building your first website for API documentation 16
  17. 17. What is an IDE?  IDE is an integrated development environment.  Used by your developers to write code.  Provides a specialized editor for writing code.  Supports building the libraries provide as part of the API. STC Summit 2015 Survival strategies: Building your first website for API documentation 17
  18. 18. Explore the IDE  Install the IDE on your computer.  Work through tutorials that explain how to use the IDE.  Get familiar with the IDE to understand how developers build applications using your API. STC Summit 2015 Survival strategies: Building your first website for API documentation 18
  19. 19. Experiment with the API’s language  Take advantage of free learning opportunities:  MSDN - Microsoft provides free videos and training materials in C#.  The Java Tutorials - Oracle offers free training in Java.  Check out study guides for language certifications with overviews of key language features.  Build the sample applications to learn about features of the language.  Plan about twenty hours to ramp up on terminology and understand basic code samples. STC Summit 2015 Survival strategies: Building your first website for API documentation 19
  20. 20. Content for your first API website  Consider the audience for your API documentation.  Write for users with a range of technical expertise:  Entry-level developers just out of college  Developers with no prior background in the technology used by your API  Experienced developers who just want information about a specific API feature STC Summit 2015 Survival strategies: Building your first website for API documentation 20
  21. 21. Common types of content  Concept information - a high-level overview of the API architecture, and other features.  Getting started materials - instructions for installing the SDK, setting up an dev environment, and implementing a sample application.  Code samples - includes fragments of code, detailed code samples, and sample applications.  Reference or class libraries – includes developer comments and other information automatically generated from elements in the API source code. STC Summit 2015 Survival strategies: Building your first website for API documentation 21
  22. 22. Example: Class libraries STC Summit 2015 Survival strategies: Building your first website for API documentation 22 Method in the source code for the TechWriter class.
  23. 23. Example: Class libraries STC Summit 2015 Survival strategies: Building your first website for API documentation 23
  24. 24. Code samples  Include well-written code samples for all key API operations.  Establish a clear strategy for writing code samples with your development team.  Reuse code from sample applications or QA test cases.  Use syntax highlighting to enhance readability by color coding specific words in your code samples. STC Summit 2015 Survival strategies: Building your first website for API documentation 24
  25. 25. Example: Syntax highlighting STC Summit 2015 Survival strategies: Building your first website for API documentation 25 Comments in green. Reserved words in blue. Variable names in black.
  26. 26. Example: Syntax highlighting STC Summit 2015 Survival strategies: Building your first website for API documentation 26
  27. 27. Types of code samples  Short snippets - illustrate a single feature discussed in your conceptual or overview content. This code may consist of two or three lines.  Codes samples for methods or classes - provide a detailed example of a specific API feature. They may be used in a tutorial, and consist of ten or more lines.  Sample applications - illustrate complex projects and application design with your API. These samples may include multiple files. STC Summit 2015 Survival strategies: Building your first website for API documentation 27
  28. 28. Tools for building your site  Tools for writing conceptual content, tutorials, and other explanatory material, such as Madcap Flare, Robohelp, Confluence, oXygen, or Epic.  Tools for generating the class libraries, such as Sandcastle, Javadoc, DoxyGen, or NDoc3.  Repository for storing source code influences the collaboration of writers and developers while updating code comments. STC Summit 2015 Survival strategies: Building your first website for API documentation 28
  29. 29. Evaluate tool features  Authoring and collaboration capabilities.  Learning curve for the documentation team and SMEs.  General web publishing functionality.  Search and content tagging.  Community capabilities.  Options for integrating with source control products.  Flexible formatting and other customization options.  Costs for proprietary versus open source tools.  Compatibility with other tools used by your 0rganization. STC Summit 2015 Survival strategies: Building your first website for API documentation 29
  30. 30. Example: MadCap vs Confluence STC Summit 2015 Survival strategies: Building your first website for API documentation 30
  31. 31. Investigate your user’s experience  Learn about how developers navigate your website and their expectations for it.  Take a no frills approach to usability testing as described in Rocket Surgery Made Easy by Steve Krug.  Devise usability tests tailored to your API and audience.  Structure your usability tests to take about an hour, so they are a minimal investment of time. STC Summit 2015 Survival strategies: Building your first website for API documentation 31
  32. 32. Performing usability testing Consider recruiting these test subjects and look for common usability issues:  External developers who want to used your API  Current developers working on projects other than the API  New hires for development teams, including entry- level and experienced developers STC Summit 2015 Survival strategies: Building your first website for API documentation 32
  33. 33. Example: Usability testing STC Summit 2015 Survival strategies: Building your first website for API documentation 33 Shifted from API names to task-based titles for usability.
  34. 34. What is SEO?  An acronym for search engine optimization.  Includes the process of ensuring that your content is discoverable by major search engines.  Involves identifying general information about how search engines index the contents of your site. STC Summit 2015 Survival strategies: Building your first website for API documentation 34
  35. 35. Use SEO to enhance usability  Learn about developer preferences for searching rather than browsing information.  Use analytics to identify major search engines used to find information about your public APIs and the terms being searched.  Add metadata and use other techniques to ensure that search engines return your pages.  Test searching on your site. STC Summit 2015 Survival strategies: Building your first website for API documentation 35
  36. 36. Example: Metadata tags STC Summit 2015 Survival strategies: Building your first website for API documentation 36
  37. 37. Example: Metadata tags for SEO STC Summit 2015 Survival strategies: Building your first website for API documentation 37
  38. 38. Look for automation opportunities  Use content modelling to establish a semantic structure based on information types, such as concepts, tasks, references, or samples.  Identify manual tasks used to build your API documentation project:  Generating class libraries - tools used to generate this highly structured content provide output that you produce by an automated build process.  Code samples - explore an automated solution for adding them to the website, which ensures that they stay up-to-date.  Establish consistent naming conventions for files and other content elements to facilitate building integration points in your documentation project.  Learn an OS scripting language, such as shell, batch file programming, or PowerShell. STC Summit 2015 Survival strategies: Building your first website for API documentation 38
  39. 39. Example: Naming Conventions STC Summit 2015 Survival strategies: Building your first website for API documentation 39 Name your HTML elements and region tags.
  40. 40. Strategize for the future  Look for opportunities to balance current goals with the future growth and evolution of your site.  Watch for new trends in technical communications to help you strategize for future iterations of your site.  Continually reassess the needs of your developer community.  Use the strategies discussed here to organize your goals and resources.  Devise a successful survival strategy! Don’t get voted off the island! STC Summit 2015 Survival strategies: Building your first website for API documentation 40
  41. 41. Questions STC Summit 2015 Survival strategies: Building your first website for API documentation 41
  42. 42. Resources API writing  Lessons Learned as a Novice API Writer by Mary Linderman in Intercom (September 2014) Business value and adoption strategies  APIs: A Strategy Guide by Jacobsen, Brail, and Woods  APIs can be strategic tools to unlock business values by Teresa Tung and Michael J. Blitz  Explaining the API Revolution to your CEO by Dan Woods  The Strategic Value of APIs by Bala Iyer and Mohan Subramaniam STC Summit 2015 Survival strategies: Building your first website for API documentation 42
  43. 43. Resources Technical skills  Exam Ref 70-483: Programming in C# by Wouter De Kort  Head First C# by Jennifer Greene and Andrew Stellman  Head First Java by Kathy Sierra and Bert Bates Sample API documentation  Android  Flickr  Java™ Platform API Specification  Jquery  .NET Framework Class Library  Vimeo STC Summit 2015 Survival strategies: Building your first website for API documentation 43
  44. 44. Resources Tools  DoxyGen  Google Webmaster Tools  Javadoc  Markdown  NDoc3  google-code-prettify  Sandcastle  Syntax Highlighter Usability testing  Rocket Surgery Made Easy by Steve Krug STC Summit 2015 Survival strategies: Building your first website for API documentation 44
  45. 45. Contact Information  Mary Linderman - linderman.mary@gmail.com  Andrei Essaoulov - yesaulov@gmail.com STC Summit 2015 Survival strategies: Building your first website for API documentation 45

×