API documentation writing is a growing field as more applications use APIs. The role requires technical writing skills as well as strong domain knowledge of programming languages and tools. API documentation writers create reference materials that explain how developers can utilize APIs through documentation of resources, endpoints, parameters and code samples. While requiring technical skills, the role differs from traditional technical writing through its focus on reference content for other developers rather than task-based content for general audiences. Overall, API documentation writing presents opportunities for technical writers to expand their skills and participate in an important area of software development.
Publishing strategies for API documentationTom Johnson
Most of the common tools for publishing help material fall short when it comes to API documentation. Much API documentation (such as for Java, C++, or .NET APIs) is generated from comments in the source code. Their outputs don’t usually integrate with other help material, such as programming tutorials or scenario-based code samples.
REST APIs are a breed of their own, with almost no standard tools for generating documentation from the source. The variety of outputs for REST APIs are as diverse as the APIs themselves, as you can see by browsing the 11,000+ web APIs on programmableweb.com.
As a technical writer, what publishing strategies do you use for API documentation? Do you leave the reference material separate from the tutorials and code samples? Do you convert everything to DITA and merge it into a single output? Do you build your own help system from scratch that imports your REST API information?
There’s not a one-size-fits-all approach. In this presentation, you’ll learn a variety of publishing strategies for different kinds of APIs, with examples of what works well for developer audiences. No matter what kind of API you’re working with, you’ll benefit from this survey of the API doc publishing scene.
- See more at: http://idratherbewriting.com
This presentation covers how to document REST APIs. For accompanying notes, see http://idratherbewriting.com/restapicourse. This presentation is geared towards technical writers. The focus is with REST APIs, not platform-specific APIs such as Java.
Publishing strategies for API documentationTom Johnson
Most of the common tools for publishing help material fall short when it comes to API documentation. Much API documentation (such as for Java, C++, or .NET APIs) is generated from comments in the source code. Their outputs don’t usually integrate with other help material, such as programming tutorials or scenario-based code samples.
REST APIs are a breed of their own, with almost no standard tools for generating documentation from the source. The variety of outputs for REST APIs are as diverse as the APIs themselves, as you can see by browsing the 11,000+ web APIs on programmableweb.com.
As a technical writer, what publishing strategies do you use for API documentation? Do you leave the reference material separate from the tutorials and code samples? Do you convert everything to DITA and merge it into a single output? Do you build your own help system from scratch that imports your REST API information?
There’s not a one-size-fits-all approach. In this presentation, you’ll learn a variety of publishing strategies for different kinds of APIs, with examples of what works well for developer audiences. No matter what kind of API you’re working with, you’ll benefit from this survey of the API doc publishing scene.
- See more at: http://idratherbewriting.com
This presentation covers how to document REST APIs. For accompanying notes, see http://idratherbewriting.com/restapicourse. This presentation is geared towards technical writers. The focus is with REST APIs, not platform-specific APIs such as Java.
Publishing API documentation -- WorkshopTom Johnson
These slides are from the REST API documentation workshop that I gave at the STC Summit 2015. For more details, see http://idratherbewriting.com/publishingapidocs.
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.
API Documentation Workshop tcworld India 2015Tom Johnson
This is a workshop I gave on API documentation at tcworld India 2015. The workshop covers 3 main areas:
- General overview of API documentation
- Deep dive into REST API documentation
- Deep dive into Javadoc documentation
API Description Languages: Which is the Right One for Me?Akana
SOA Software Director of API Strategy, Laura Heritage, discusses new ways to describe and document APIs have emerged such as Swagger, RAML, API Blueprint and others, each taking a slightly different approach. Please join us in this webinar to hear how these description languages differ and how to choose right one for your API.
Cherryleaf’s Ellis Pratt will be speaking at Lavacon’s first European conference. This will be held on 5-8 June, at the Trinity College Conference Centre, Dublin. Ellis’ presentation will be on the 7th June 2016
An introduction to a popular framework for Service Oriented REST APIs, Proof of Concepts and Rapid Development. Swagger is a indispensable tool for Software Engineers, Developers and Architects.
KPIs for APIs (and how API Calls are the new Web Hits, and you may be measuri...John Musser
How do you measure API success? What KPIs do APIs need? What mistakes should I avoid? Find out what you should, and shouldn't, be measuring as part of your API program in this Business of APIs Conference NYC talk. Dive into a breadth of API metrics, the 6 keys to better API metrics, and the traps to beware of (the important do's and don'ts). Also real-world API case studies show who measures what.
apidays LIVE New York - API Code First vs Design First by Phil Sturgeonapidays
apidays LIVE New York - API for Legacy Industries: Banking, Insurance, Healthcare and Retail
API Code First vs Design First
Phil Sturgeon, Author of "APIs you won't hate" & Developer Advocate at Stoplight
Louise Fahey - Mapping your path in tech comms: Surviving the early years (TC...Louise Fahey
*Powerpoint only - for notes, see: http://www.slideshare.net/louisefahey3/louise-fahey-mapping-your-path-in-tech-comms-surviving-the-early-years-tcuk-2016*
Are you a newbie to tech comms? Or are you a tech comms expert charged with the training and development of a newbie? If so, this presentation is for you!
Using my first two years working in tech comms as a reference, I will share tips and tricks that are key to the development of new starters in the field.
This includes advice for breaking into technical communication, entering the profession from a non-technical background, getting over the steep learning curve at the beginning, the key skills you should focus on developing, as well as much more!
PDF, audio, and voiceover are now available on designintechreport.wordpress.com
Today’s most beloved technology products and services balance design and engineering in a way that perfectly blends form and function. Businesses started by designers have created billions of dollars of value, are raising billions in capital, and VC firms increasingly see the importance of design. The third annual Design in Tech Report examines how design trends are revolutionizing the entrepreneurial and corporate ecosystems in tech. This report covers related M&A activity, new patterns in creativity × business, and the rise of computational design.
Publishing API documentation -- WorkshopTom Johnson
These slides are from the REST API documentation workshop that I gave at the STC Summit 2015. For more details, see http://idratherbewriting.com/publishingapidocs.
Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson
This is a presentation I gave to the Southwestern Ontario STC chapter on API documentation on Feb 2, 2015. For more details, see my blog at http://idratherbewriting.com. You can listen to the recorded presentation here: http://youtu.be/I8rGe2w1sAo.
API Documentation Workshop tcworld India 2015Tom Johnson
This is a workshop I gave on API documentation at tcworld India 2015. The workshop covers 3 main areas:
- General overview of API documentation
- Deep dive into REST API documentation
- Deep dive into Javadoc documentation
API Description Languages: Which is the Right One for Me?Akana
SOA Software Director of API Strategy, Laura Heritage, discusses new ways to describe and document APIs have emerged such as Swagger, RAML, API Blueprint and others, each taking a slightly different approach. Please join us in this webinar to hear how these description languages differ and how to choose right one for your API.
Cherryleaf’s Ellis Pratt will be speaking at Lavacon’s first European conference. This will be held on 5-8 June, at the Trinity College Conference Centre, Dublin. Ellis’ presentation will be on the 7th June 2016
An introduction to a popular framework for Service Oriented REST APIs, Proof of Concepts and Rapid Development. Swagger is a indispensable tool for Software Engineers, Developers and Architects.
KPIs for APIs (and how API Calls are the new Web Hits, and you may be measuri...John Musser
How do you measure API success? What KPIs do APIs need? What mistakes should I avoid? Find out what you should, and shouldn't, be measuring as part of your API program in this Business of APIs Conference NYC talk. Dive into a breadth of API metrics, the 6 keys to better API metrics, and the traps to beware of (the important do's and don'ts). Also real-world API case studies show who measures what.
apidays LIVE New York - API Code First vs Design First by Phil Sturgeonapidays
apidays LIVE New York - API for Legacy Industries: Banking, Insurance, Healthcare and Retail
API Code First vs Design First
Phil Sturgeon, Author of "APIs you won't hate" & Developer Advocate at Stoplight
Louise Fahey - Mapping your path in tech comms: Surviving the early years (TC...Louise Fahey
*Powerpoint only - for notes, see: http://www.slideshare.net/louisefahey3/louise-fahey-mapping-your-path-in-tech-comms-surviving-the-early-years-tcuk-2016*
Are you a newbie to tech comms? Or are you a tech comms expert charged with the training and development of a newbie? If so, this presentation is for you!
Using my first two years working in tech comms as a reference, I will share tips and tricks that are key to the development of new starters in the field.
This includes advice for breaking into technical communication, entering the profession from a non-technical background, getting over the steep learning curve at the beginning, the key skills you should focus on developing, as well as much more!
PDF, audio, and voiceover are now available on designintechreport.wordpress.com
Today’s most beloved technology products and services balance design and engineering in a way that perfectly blends form and function. Businesses started by designers have created billions of dollars of value, are raising billions in capital, and VC firms increasingly see the importance of design. The third annual Design in Tech Report examines how design trends are revolutionizing the entrepreneurial and corporate ecosystems in tech. This report covers related M&A activity, new patterns in creativity × business, and the rise of computational design.
Best practices and advantages of REST APIsAparna Sharma
In this article, I am going to share the best practices and the advantages of REST APIs, as I am working with a team on a REST-based web application. Newsdata.io news API is a REST-based API that fetches news data from thousands of news websites in JSON format. Therefore, I have a basic understanding of REST APIs that I am going to share with you.
API Management Workshop (at Startupbootcamp Berlin)3scale
These are the slides from the API Management Workshop, held at the Startupbootcamp Berlin on October 17.
We covered benefits of APIs for an organisation (regardless of size, sector, stage or purpose) and gave examples of successful deployment of APIs.
We then described the typical API lifecycle:
plan/design > build/integrate > operate/manage > share/engage.
We covered many best practices and tools for each stage and gave practical demos about how to secure and manage APIs.
Slides from the workshop delivered at the Evolution of Technical Communication 2018 conference. The workshop features an introduction to REST APIs followed by hands-on activities in which the participants (technical communication professionals) put themselves in developers' shoes used and some APIs and API tools like developers.
Building A Great API - Evan Cooke, Cloudstock, December 2010Twilio Inc
Tips and tricks on how to design, package, and build a great API. We summarize some of the lessons we've learned over the years at Twilio designing and operating Voice and SMS APIs used by more then 20,000 developers.
In today’s interconnected world, APIs (Application Programming Interfaces) play a pivotal role in enabling seamless communication and data exchange between different systems. Whether you’re a seasoned developer or just starting your journey in the software industry, understanding APIs is essential. In this comprehensive guide, we’ll cover everything you need to know about APIs, from the basics to advanced concepts.
Mastering APIs is crucial for any developer aiming to build robust and scalable applications. By understanding the fundamentals and delving into advanced concepts, you’ll be equipped to design, develop, and optimize APIs effectively. In this series, I have created a set of slides, publications, and notes that cover each topic in detail.
When SaaS companies use Blendr.io – an embedded integration platform – to boost their native integrations offering, we often receive the question – “What is a good API”? At Blendr.io, we have been working with hundreds of API’s and compiled an API Checklist for SaaS companies.
COVID-19: The future of organisations and the future of technical communicationEllis Pratt
The COVID-19 coronavirus is having a huge impact on people and organisations. With so many things that could be about to change, how should technical communicators respond? What’s your plan for the future?
In this presentation, we looked at:
How organisations might change during and after the COVID-19 lockdown
What that means for technical communication, and how you can come back stronger than ever
What technical communicators can do to help, and how you can deal with this crisis
How other technical communicators responded when we asked them for their views
Structured writing presentation to London Content Strategy MeetupEllis Pratt
Content can often seem like jelly - messy and hard to manage. In this presentation, we'll look at whether you can reduce this messiness through structured writing. In this overview of the topic, we'll explore what is structured writing, what it promises to give its adopters, the different standards, and the challenges that come with using structured writing.
If you've wanted to get a handle on structured content and how it could work to make your content work better, join us for this informative session.
Our presenter, Ellis Pratt, is a Consulting Technical Communicator and Director at Cherryleaf, a technical writing services company. He has been working in technical communication since the early 1990s. He has a degree in Business Studies. He is also:
- Member of the Institute of Scientific and Technical Communicators
- Associate of the Institution of Engineering and Technology
- An ISTC Management Council member
In 2017, he was listed as one of the top 25 Content Experience influencers in the world.
Ellis was a contributor to two books: Current Practices and Trends in Technical Communication, and The Language of Technical Communication.
Writing at 240 words per minute - The Open Steno ProjectEllis Pratt
Draft slides for a presentation on how the Open Steno movement and Plover software is making stenography accessible to more people, and its uses in IT.
The changing nature of technical content (tekom tcworld 2013 conference)Ellis Pratt
There have been many developments in creating documentation systems, with the assumption that the nature of the content - the tone of voice, the writing style - should remain essentially the same. We investigate whether the tried-and-tested technical communication writing styles from past decades still make sense today. We look at the reasons why some organisations, such as Facebook, Google & Mozilla, might be "breaking the rules" in the User Assistance they provide. We also look at how structured, adaptable, intelligent content becomes important for organisations that do decide to change.
Adobe Day Europe panel discussion slides: Assisting the millennial user – cha...Ellis Pratt
Here are the slides the panel put together for the Adobe Day Europe discussion on "Assisting the millennial user – challenges and opportunities in the decade ahead". We didn't get time to cover all of the topics in the time we had available.
You win! Applying gamification to user assistanceEllis Pratt
Slides from UAEurope 11 conference: You win! Applying Gamification to User Assistance.
For more information on applying gamification to technical communication and other documentation strategies, feel free to contact me.
Slides from our presentation to Year 11 children on writing as career in IT. We looked at the different writing postions in companies such as Apple, and then looked at the role of the Technical Author/Writer. The class had to write an instruction manual for a new eco-messaging product (aka a typewriter).
Transcript: Selling digital books in 2024: Insights from industry leaders - T...BookNet Canada
The publishing industry has been selling digital audiobooks and ebooks for over a decade and has found its groove. What’s changed? What has stayed the same? Where do we go from here? Join a group of leading sales peers from across the industry for a conversation about the lessons learned since the popularization of digital books, best practices, digital book supply chain management, and more.
Link to video recording: https://bnctechforum.ca/sessions/selling-digital-books-in-2024-insights-from-industry-leaders/
Presented by BookNet Canada on May 28, 2024, with support from the Department of Canadian Heritage.
LF Energy Webinar: Electrical Grid Modelling and Simulation Through PowSyBl -...DanBrown980551
Do you want to learn how to model and simulate an electrical network from scratch in under an hour?
Then welcome to this PowSyBl workshop, hosted by Rte, the French Transmission System Operator (TSO)!
During the webinar, you will discover the PowSyBl ecosystem as well as handle and study an electrical network through an interactive Python notebook.
PowSyBl is an open source project hosted by LF Energy, which offers a comprehensive set of features for electrical grid modelling and simulation. Among other advanced features, PowSyBl provides:
- A fully editable and extendable library for grid component modelling;
- Visualization tools to display your network;
- Grid simulation tools, such as power flows, security analyses (with or without remedial actions) and sensitivity analyses;
The framework is mostly written in Java, with a Python binding so that Python developers can access PowSyBl functionalities as well.
What you will learn during the webinar:
- For beginners: discover PowSyBl's functionalities through a quick general presentation and the notebook, without needing any expert coding skills;
- For advanced developers: master the skills to efficiently apply PowSyBl functionalities to your real-world scenarios.
Software Delivery At the Speed of AI: Inflectra Invests In AI-Powered QualityInflectra
In this insightful webinar, Inflectra explores how artificial intelligence (AI) is transforming software development and testing. Discover how AI-powered tools are revolutionizing every stage of the software development lifecycle (SDLC), from design and prototyping to testing, deployment, and monitoring.
Learn about:
• The Future of Testing: How AI is shifting testing towards verification, analysis, and higher-level skills, while reducing repetitive tasks.
• Test Automation: How AI-powered test case generation, optimization, and self-healing tests are making testing more efficient and effective.
• Visual Testing: Explore the emerging capabilities of AI in visual testing and how it's set to revolutionize UI verification.
• Inflectra's AI Solutions: See demonstrations of Inflectra's cutting-edge AI tools like the ChatGPT plugin and Azure Open AI platform, designed to streamline your testing process.
Whether you're a developer, tester, or QA professional, this webinar will give you valuable insights into how AI is shaping the future of software delivery.
Accelerate your Kubernetes clusters with Varnish CachingThijs Feryn
A presentation about the usage and availability of Varnish on Kubernetes. This talk explores the capabilities of Varnish caching and shows how to use the Varnish Helm chart to deploy it to Kubernetes.
This presentation was delivered at K8SUG Singapore. See https://feryn.eu/presentations/accelerate-your-kubernetes-clusters-with-varnish-caching-k8sug-singapore-28-2024 for more details.
The Art of the Pitch: WordPress Relationships and SalesLaura Byrne
Clients don’t know what they don’t know. What web solutions are right for them? How does WordPress come into the picture? How do you make sure you understand scope and timeline? What do you do if sometime changes?
All these questions and more will be explored as we talk about matching clients’ needs with what your agency offers without pulling teeth or pulling your hair out. Practical tips, and strategies for successful relationship building that leads to closing the deal.
"Impact of front-end architecture on development cost", Viktor TurskyiFwdays
I have heard many times that architecture is not important for the front-end. Also, many times I have seen how developers implement features on the front-end just following the standard rules for a framework and think that this is enough to successfully launch the project, and then the project fails. How to prevent this and what approach to choose? I have launched dozens of complex projects and during the talk we will analyze which approaches have worked for me and which have not.
4. Overview
1. What is an API?
2. APIs and the role of documentation
3. The role of an API documentation writer
4. The skills you need
5. The tools
6. Becoming an API documentation writer
Image: Tim Peake
7. Lots of websites use
information from APIs
Find a GP near to your
postcode
Information is requested from
the NHS Choices API and
displayed on the web page
www.whereilive.norfolk.gov.uk
9. What developers do with
APIs
API
App
Developer
Developers write code to take the data provided in the response and use it in
their applications (“parsing”)
There is code in the Web page
to request data and then
display the data on a map
NHS application
containing list of
GP practices in a
database
11. http protocols
Users make requests for the
resources on a Web server.
The server returns responses
containing the information.
API
http request ->
<- http response
14. A hospital API
An API will consist of a set of
rules describing how an
application can interact with it
and
the mechanisms that allow
such interaction to happen.
API
15. Example - Your NHS number
The API might state it wants
the NHS number in:
numerical (9434765919)
or
alphanumerical string
(“943-476-5919”)
format.
18. API Rules
A hospital API will consist of a
set of rules describing how an
application can interact with it
(specifically, a resource):
Create/Add information (Post)
Request information (Get)
Update information (Put/Patch)
Delete information (Delete)
(and run an application)
19. Requests to an API
Get me Jane Brown’s records
Get me a list of all the patients
leaving hospital today
Get me the Consultant’s name
who is attached to Mrs Brown
etc
GET http://ABC-hospital.nhs/patient/
JaneBrown
curl --get -k --include "http://ABC-
hospital.nhs/patient/?name=jane
brown&NHS=9434765900" -H "X-Key:
ABC12345" -H "Accept: text/plain
curl -X GET -H "Cache-Control: no-
cache" -H "Postman-Token: 97bb9ba5-
f763-208e-b9e4-5d7bd3861835" "https://
fhir-open-api-dstu2.smarthealthit.org/
Patient/1551992"
20. How do the API team create
APIs?
They may use an API
Specification
They may make REST calls in
the programming language
they are using
API
API Team
21. They may use a type of API
Specification
API Specification tools can
generate the code for REST
calls in a programming
language.
Programmers can then add
this code to their application.
23. What content goes into an
API document?
Content Buzzword
A clear definition of what
resource it represents
Resource description
The accepted input
Parameters, Request
submission example
The produced output Request response example
Links (where can you go to find
what exactly)
Endpoints
24. Automatically generated
content
When you describe your API
using the Swagger or RAML
specification, some tools can
read those specifications will
generate an interactive
documentation output.
26. Explain what it does
What it does
The overall process
Any underlying concepts
27. Signing up for an account
Signing up for an account
Getting API authorisation keys
28. The 3-30-3 goal
The 3-30-3 goal
3 seconds - what it does
30 seconds - why you should
use it
3 minutes - to do something
29. TTFHW - Time to first "Hello
World"
A simple exercise
How quickly you can get an
application to output “Hello
World”?
For APIs it might be how to
construct a request and
receive a valid response.
31. Why do we need code
samples?
REST APIs aren’t tied to a
specific programming
language
So developers may need
advice on how to submit HTTP
requests in their particular
programming language
32. Creating code samples
Some API providers decide to
provide one code sample
(usually in cURL) and let the
developer extrapolate the
format in his or her own
programming language.
curl --get -k --include
"http://ABC-hospital.nhs/
patient/?name=jane
brown&NHS=9434765900" -H "X-
Key: ABC12345" -H "Accept:
text/plain
33. Creating code samples
Others want to encourage
developers to use their API,
and want to make it as easy
as possible by providing code
samples.
34. Creating code samples -
Don’t panic!
In some cases, developers
supply the code samples
You briefly add comments to
the code samples.
The patterns for making REST
requests in different
programming languages
follow a common template.
39. There are some differences
Technical Author API Writer
Task-based content Reference-based content
To a non-technical audience To a technical audience
Re-use content Single use
Localise English only
48. The grass is greener?
Lots of software developer are
currently working on APIs
49. Let’s look at some vacancies
On reed.co.uk from mid-
February 2016……
50.
51.
52. Search carried out on 15/2/2016
Of the 5,000 UK
Technical Authors
on LinkedIn
173
included “API” in their
profile
53. Finding a unicorn
“Finding a technical writer who
commands
a high degree of English language
fluency
in addition to possessing a deep
technical knowledge of Java, Python,
C++, .NET, Ruby, and more
is like finding a unicorn.”
Tom Johnson
Flickr image: Owlana
54. A lot of recruitment is by
word of mouth
Following entrepreneurs as
they more from business to
business