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
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
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.
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.
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
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.
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.
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.
OpenAPI is an the emerging standard for creating, managing and consuming REST APIs. Previously named Swagger, in the last year has been adopted by the Linux Foundation and gained the support of companies like Google, Microsoft, IBM, Paypal, etc. to become a de-facto standard for APIs. In this talk we will review 3 uses cases to apply OpenAPI to enhance and speed-up our developments to create OpenAPI compliant APIs.
This is the presentation I delivered at the Liferay North American Symposium 2017 and presents our vision for making Liferay the best Headless Platform out there.
It specifically covers how we are using the power of Hypermedia + Shared Vocabularies to build APIs designed to evolve and extremely easy to use and consume
When it comes to developing progressive web apps or PWAs, you should hire ionic developer. According to experts, there isn’t anything better than Ionic for building feature-rich PWAs.
Just a few years back, lack of a standard way to document, govern or describe a contract for the APIs acted as a deterrent to API adoption within the enterprise. WSDL 2.0 and WADL provided early support, but they couldn’t truly capture the essence of RESTful APIs. Recently we have seen the emergence of several description languages. New ways to describe and document APIs have emerged such as Swagger, RAML, API Blueprint and others, each taking a slightly different approach.
When it comes to developing enterprise-level web apps using PHP, a laravel development company can be your best business partner. A new version of the framework is also available – Laravel 9. Here you’ll learn more about the framework and what the newest version brings to the table.
PhoneGap (aka Cordova) is a cross-platform framework for developing mobile apps using standard web development tools like HTML, CSS, and JavaScript. Join Troy Miles to learn how to create mobile apps with PhoneGap by building a simple but full-featured app during this hands-on class. Troy explores PhoneGap’s important capabilities, including GPS, camera, and audio recordings. Because JavaScript has a reputation as a somewhat difficult language, Troy teaches techniques for keeping your code robust and clean. To give your app the appropriate look and feel for the device on which it is running, the class will use the open source Chocolate Chip UI framework for testing. Troy shares ways to debug the code by running it as a web app, using browser development tools, or as a phone app, using the Chrome browser’s remote debugging features. Leave with the basics you need to start building your own cross-platform mobile apps.
Join us for an overview of REST, the Force.com REST API, and learn how to use that REST API with Swagger, a language-agnostic framework for describing, producing, consuming, and visualizing RESTful web services. You'll learn how Swagger can generate a Spring MVC Controller to consume the Force.com REST API, and keep client and documentation systems in sync with the server.
Beautiful REST and JSON APIs - Les Hazlewoodjaxconf
Designing a really clean and intuitive REST + JSON API is no small feat. You have to worry about resources, collections of resources, pagination, query parameters, references to other resources, which HTTP Methods to use, HTTP Caching, security, and more! And you have to make sure it lasts and doesn't break clients as you add features over time. Further, while there are many references on creating REST APIs with XML, there are many fewer references for REST + JSON.
API Developer Experience: Why it Matters, and How Documenting Your API with S...SmartBear
Whether you’re new to Swagger, or have already been using the framework for API design, there’s a good chance you still have questions about how to improve your API documentation. Creating API documentation your consumers will love can take some work, but the investment will have a significant payoff in the form of a great developer experience, easier implementation, and improved adoption of your API.
This presentation covers good developer experience in detail, focusing on why and how to provide an optimal experience for developers using your API. We will also cover how Swagger has changed the API design and documentation landscape, and finally show some good practices for API documentation using Swagger in SwaggerHub’s integrated API development platform.
Things to expect in this webinar:
What is Developer Experience (DX)?
What does it mean for an API to have good DX?
API documentation in the context of good DX?
An introduction to the Swagger framework
Designing APIs from a usability perspective using Swagger and SwaggerHub
Предлагаемый анализ провели студенты 4 курса МФТИ. Все данные были взяты из свободных источников информации, ссылки на которые приведены на слайдах.
Презентация стала отправной точкой на пути создания приложения Flickr Photo Quiz на facebook.
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.
OpenAPI is an the emerging standard for creating, managing and consuming REST APIs. Previously named Swagger, in the last year has been adopted by the Linux Foundation and gained the support of companies like Google, Microsoft, IBM, Paypal, etc. to become a de-facto standard for APIs. In this talk we will review 3 uses cases to apply OpenAPI to enhance and speed-up our developments to create OpenAPI compliant APIs.
This is the presentation I delivered at the Liferay North American Symposium 2017 and presents our vision for making Liferay the best Headless Platform out there.
It specifically covers how we are using the power of Hypermedia + Shared Vocabularies to build APIs designed to evolve and extremely easy to use and consume
When it comes to developing progressive web apps or PWAs, you should hire ionic developer. According to experts, there isn’t anything better than Ionic for building feature-rich PWAs.
Just a few years back, lack of a standard way to document, govern or describe a contract for the APIs acted as a deterrent to API adoption within the enterprise. WSDL 2.0 and WADL provided early support, but they couldn’t truly capture the essence of RESTful APIs. Recently we have seen the emergence of several description languages. New ways to describe and document APIs have emerged such as Swagger, RAML, API Blueprint and others, each taking a slightly different approach.
When it comes to developing enterprise-level web apps using PHP, a laravel development company can be your best business partner. A new version of the framework is also available – Laravel 9. Here you’ll learn more about the framework and what the newest version brings to the table.
PhoneGap (aka Cordova) is a cross-platform framework for developing mobile apps using standard web development tools like HTML, CSS, and JavaScript. Join Troy Miles to learn how to create mobile apps with PhoneGap by building a simple but full-featured app during this hands-on class. Troy explores PhoneGap’s important capabilities, including GPS, camera, and audio recordings. Because JavaScript has a reputation as a somewhat difficult language, Troy teaches techniques for keeping your code robust and clean. To give your app the appropriate look and feel for the device on which it is running, the class will use the open source Chocolate Chip UI framework for testing. Troy shares ways to debug the code by running it as a web app, using browser development tools, or as a phone app, using the Chrome browser’s remote debugging features. Leave with the basics you need to start building your own cross-platform mobile apps.
Join us for an overview of REST, the Force.com REST API, and learn how to use that REST API with Swagger, a language-agnostic framework for describing, producing, consuming, and visualizing RESTful web services. You'll learn how Swagger can generate a Spring MVC Controller to consume the Force.com REST API, and keep client and documentation systems in sync with the server.
Beautiful REST and JSON APIs - Les Hazlewoodjaxconf
Designing a really clean and intuitive REST + JSON API is no small feat. You have to worry about resources, collections of resources, pagination, query parameters, references to other resources, which HTTP Methods to use, HTTP Caching, security, and more! And you have to make sure it lasts and doesn't break clients as you add features over time. Further, while there are many references on creating REST APIs with XML, there are many fewer references for REST + JSON.
API Developer Experience: Why it Matters, and How Documenting Your API with S...SmartBear
Whether you’re new to Swagger, or have already been using the framework for API design, there’s a good chance you still have questions about how to improve your API documentation. Creating API documentation your consumers will love can take some work, but the investment will have a significant payoff in the form of a great developer experience, easier implementation, and improved adoption of your API.
This presentation covers good developer experience in detail, focusing on why and how to provide an optimal experience for developers using your API. We will also cover how Swagger has changed the API design and documentation landscape, and finally show some good practices for API documentation using Swagger in SwaggerHub’s integrated API development platform.
Things to expect in this webinar:
What is Developer Experience (DX)?
What does it mean for an API to have good DX?
API documentation in the context of good DX?
An introduction to the Swagger framework
Designing APIs from a usability perspective using Swagger and SwaggerHub
Предлагаемый анализ провели студенты 4 курса МФТИ. Все данные были взяты из свободных источников информации, ссылки на которые приведены на слайдах.
Презентация стала отправной точкой на пути создания приложения Flickr Photo Quiz на facebook.
7 Tips for Design Teams Collaborating RemotelyFramebench
So you're working with a remote team? Super cool! We're sure you have your ways of collaborating with each other. But you'll have to agree, sometimes it just gets messed up. Here are 7 tips (a 5 minute read) to help you along as you build an amazing team.
You'll also find quick tips and tricks for remote collaboration.
This slidedeck was for a talk I gave at Digital Shoreditch about the gamification or use of game artefacts within customer service.
I am still at the outset of this journey, but there is no doubt in my mind that game elements can be used to influence customer behaviour within customer service.
The premise of my talk was exploring the idea of whether game elements (badges, rewards, levelling etc) can be used to influence customers to self-serve rather than call.
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.
You've got some awesome code that you've written, which you want to share with the community. Sure, you could simply post it on GitHub and be done with it, but is that the best way to share your work? What are the additional steps needed to share your code in a way that it will actually get used by the larger world? I'll discuss options for hosting , licensing, versioning, packaging, documenting, building, testing and even contributing to your code. All the things that will make someone else say - I want to use this!
One of the effective PHP Frameworks is the Code Igniter. Web applications with advanced features can be readied using the Code Igniter. Simpler for the beginners, CI follows an MVC (Model View Controller) pattern, thereby enabling in easy learning. Also, due to the usage of conventional PHP coding, the existing codes can be ported using this PHP framework. Also the simplicity with which it works and the speed that it has when compared to the other frameworks, is definitely considerable.
Docs as Part of the Product - Open Source Summit North America 2018Den Delimarsky
The presentation showcased at the Open Source Summit North America 2018 in Vancouver, BC. It covers the learnings from transitioning the MSDN site functionality and content to docs.microsoft.com.
Jennifer Rondeau and Margaret Eker presentation from Write The Docs Prague, 2016:
Treating docs as code, an approach that more and more teams and companies are moving toward, involves more than putting the two together in a source repository. We discuss some of the details that often get lost in as dev and docs learn to work together in new ways. Because if all we do is put doc files next to code files in source control, or use parts of the same workflow for code and docs, we're still isolating docs as a separate sort of responsibility, free from the obligations of systematic review and testing without which code would never be accepted into production.
Hot Topics: The DuraSpace Community Webinar Series,
“Introducing DSpace 7: Next Generation UI”
Curated by Claire Knowles, Library Digital Development Manager, The University of Edinburgh.
Introducing DSpace 7
February 28, 2017 presented by: Claire Knowles - The University of Edinburgh, Art Lowel - Atmire, Andrea Bollini - 4Science, Tim Donohue – DuraSpace
PHP is the King, nodejs is the Prince and Lua is the fool.
An overview about how the IT architecture changed at Namshi, a fashion e-commerce based in Dubai
These slides focus on documentation for REST APIs. See http://idratherbewriting.com for more detail. For the video recording, see http://youtu.be/0yfNd7tzH2Q. This deep dive is the second slide deck I used in the presentation.
API Workshop: Deep dive into code samplesTom Johnson
See http://idratherbewriting.com for more details. This was the third slidedeck I used in my presentation. Most of these slides repeat what I presented as a soap! conference webinar in Poland.
Perfecting the audio narration in instructional videoTom Johnson
This is a presentation I gave Oct 2014 at Information Development World in San Jose. For more information, see idratherbewriting.com or more specifically, this post: http://bit.ly/1sWgdo2. That bitly link contains the audio recording and the slides with the media embedded.
Why users can't find answers in help materialTom Johnson
See this post on my blog for more details: http://idratherbewriting.com/2013/10/23/recording-and-slides-for-why-users-cant-find-answers-in-help-presentation-to-stc-silicon-valley/
Additionally, you can listen and watch the youtube recording here: https://www.youtube.com/watch?v=49F3rBSO_Vs
Producing Professional Sounding Audio in Video TutorialsTom Johnson
I gave this presentation on voice over techniques at Lavacon.org 2012. These four voice over tips cover pitch, speed, tone, and enunciation -- the main qualities of a good voice over reading, in my opinion. I have some sample audio files and video clips. On these slides, the images link to the clips, which are on other websites.
Dev Dives: Train smarter, not harder – active learning and UiPath LLMs for do...UiPathCommunity
💥 Speed, accuracy, and scaling – discover the superpowers of GenAI in action with UiPath Document Understanding and Communications Mining™:
See how to accelerate model training and optimize model performance with active learning
Learn about the latest enhancements to out-of-the-box document processing – with little to no training required
Get an exclusive demo of the new family of UiPath LLMs – GenAI models specialized for processing different types of documents and messages
This is a hands-on session specifically designed for automation developers and AI enthusiasts seeking to enhance their knowledge in leveraging the latest intelligent document processing capabilities offered by UiPath.
Speakers:
👨🏫 Andras Palfi, Senior Product Manager, UiPath
👩🏫 Lenka Dulovicova, Product Program Manager, UiPath
GraphRAG is All You need? LLM & Knowledge GraphGuy Korland
Guy Korland, CEO and Co-founder of FalkorDB, will review two articles on the integration of language models with knowledge graphs.
1. Unifying Large Language Models and Knowledge Graphs: A Roadmap.
https://arxiv.org/abs/2306.08302
2. Microsoft Research's GraphRAG paper and a review paper on various uses of knowledge graphs:
https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/
Connector Corner: Automate dynamic content and events by pushing a buttonDianaGray10
Here is something new! In our next Connector Corner webinar, we will demonstrate how you can use a single workflow to:
Create a campaign using Mailchimp with merge tags/fields
Send an interactive Slack channel message (using buttons)
Have the message received by managers and peers along with a test email for review
But there’s more:
In a second workflow supporting the same use case, you’ll see:
Your campaign sent to target colleagues for approval
If the “Approve” button is clicked, a Jira/Zendesk ticket is created for the marketing design team
But—if the “Reject” button is pushed, colleagues will be alerted via Slack message
Join us to learn more about this new, human-in-the-loop capability, brought to you by Integration Service connectors.
And...
Speakers:
Akshay Agnihotri, Product Manager
Charlie Greenberg, Host
Let's dive deeper into the world of ODC! Ricardo Alves (OutSystems) will join us to tell all about the new Data Fabric. After that, Sezen de Bruijn (OutSystems) will get into the details on how to best design a sturdy architecture within ODC.
Epistemic Interaction - tuning interfaces to provide information for AI supportAlan Dix
Paper presented at SYNERGY workshop at AVI 2024, Genoa, Italy. 3rd June 2024
https://alandix.com/academic/papers/synergy2024-epistemic/
As machine learning integrates deeper into human-computer interactions, the concept of epistemic interaction emerges, aiming to refine these interactions to enhance system adaptability. This approach encourages minor, intentional adjustments in user behaviour to enrich the data available for system learning. This paper introduces epistemic interaction within the context of human-system communication, illustrating how deliberate interaction design can improve system understanding and adaptation. Through concrete examples, we demonstrate the potential of epistemic interaction to significantly advance human-computer interaction by leveraging intuitive human communication strategies to inform system design and functionality, offering a novel pathway for enriching user-system engagements.
UiPath Test Automation using UiPath Test Suite series, part 4DianaGray10
Welcome to UiPath Test Automation using UiPath Test Suite series part 4. In this session, we will cover Test Manager overview along with SAP heatmap.
The UiPath Test Manager overview with SAP heatmap webinar offers a concise yet comprehensive exploration of the role of a Test Manager within SAP environments, coupled with the utilization of heatmaps for effective testing strategies.
Participants will gain insights into the responsibilities, challenges, and best practices associated with test management in SAP projects. Additionally, the webinar delves into the significance of heatmaps as a visual aid for identifying testing priorities, areas of risk, and resource allocation within SAP landscapes. Through this session, attendees can expect to enhance their understanding of test management principles while learning practical approaches to optimize testing processes in SAP environments using heatmap visualization techniques
What will you get from this session?
1. Insights into SAP testing best practices
2. Heatmap utilization for testing
3. Optimization of testing processes
4. Demo
Topics covered:
Execution from the test manager
Orchestrator execution result
Defect reporting
SAP heatmap example with demo
Speaker:
Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP
Neuro-symbolic is not enough, we need neuro-*semantic*Frank van Harmelen
Neuro-symbolic (NeSy) AI is on the rise. However, simply machine learning on just any symbolic structure is not sufficient to really harvest the gains of NeSy. These will only be gained when the symbolic structures have an actual semantics. I give an operational definition of semantics as “predictable inference”.
All of this illustrated with link prediction over knowledge graphs, but the argument is general.
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.
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.
PHP Frameworks: I want to break free (IPC Berlin 2024)Ralf Eggert
In this presentation, we examine the challenges and limitations of relying too heavily on PHP frameworks in web development. We discuss the history of PHP and its frameworks to understand how this dependence has evolved. The focus will be on providing concrete tips and strategies to reduce reliance on these frameworks, based on real-world examples and practical considerations. The goal is to equip developers with the skills and knowledge to create more flexible and future-proof web applications. We'll explore the importance of maintaining autonomy in a rapidly changing tech landscape and how to make informed decisions in PHP development.
This talk is aimed at encouraging a more independent approach to using PHP frameworks, moving towards a more flexible and future-proof approach to PHP development.
Key Trends Shaping the Future of Infrastructure.pdfCheryl Hung
Keynote at DIGIT West Expo, Glasgow on 29 May 2024.
Cheryl Hung, ochery.com
Sr Director, Infrastructure Ecosystem, Arm.
The key trends across hardware, cloud and open-source; exploring how these areas are likely to mature and develop over the short and long-term, and then considering how organisations can position themselves to adapt and thrive.
Smart TV Buyer Insights Survey 2024 by 91mobiles.pdf91mobiles
91mobiles recently conducted a Smart TV Buyer Insights Survey in which we asked over 3,000 respondents about the TV they own, aspects they look at on a new TV, and their TV buying preferences.
"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.
7. Presentation outline
Native API
Docs
REST API
Docs
10 Best
Practices
Topics not covered:
• Writing the technical content
• Interacting with developers
• Learning to read code
• Understanding the different languages
• Commenting on code samples
• Creating getting started, hello world tutorials
8.
9. Some basics about the API landscape
System B
System A
API
Lots of different types
of APIs – for example:
1. Native APIs that you
download and add
to your project
before compiling.
2. REST APIs that you
access through
HTTP web requests.
11. The concept of auto-doc
/**
* Reverses the order of the elements in the specified list.<p>
*
* This method runs in linear time.
*
*
* @param list the list whose elements are to be reversed.
* @throws UnsupportedOperationException if the specified list or
* its list-iterator does not support the <tt>set</tt>
operation.
*/
public static void reverse(List<?> list) {
int size = list.size()
if (size < REVERSE_THRESHOLD || list instanceof
RandomAccess) {
for (int i=0, mid=size>>1, j=size-1; i<mid;
i++, j--)
swap(list, i, j);
} else {
…
Add documentation in the
source code, structuring it with
specific syntax that a
documentation generator can
read.
13. Javadoc
- Commonly used.
- Works only for Java.
- Run it from your IDE.
- Automate into builds.
- Explore other doclets.
- Has frame-based -
output.
- Can skin with CSS.
- Looks professional.
14. Doxygen
- Commonly used.
- Works with Java, C++,
C#, and others.
- Has easy front-end GUI.
- Point it at your source
files.
- Automate into builds.
- Can include non-source
files (Markdown).
- Frame-based output.
- Can skin.
15. Doxygen has GUI front-end
Specify the
source directory
of your files.
16. Pros of in-source documentation
- Avoids documentation
drift
- Allows the person who
creates the code (and
so best understands it)
to also document it
- Includes tooltips when
others incorporate the
library into their
projects
Continental drift
Doc Src Src
Doc
17. Cons of in-source documentation
1. Subject to Curse of
Knowledge
2. Not task-focused
3. Suffers from lack of
ownership
4. Doesn’t integrate with
other content
5. Gives illusion of having
real doc
18. Problem 1: Curse of Knowledge
A developer who
creates the API
may assume too
much of the
audiences’
technical ability.
As a result, the
descriptions
aren’t helpful.
19. Problem 2: Not task-focused
Auto-doc is feature-based
doc approach.
Task-based doc includes
multiple calls and
workflows in support of
goals. It might make use
of several different
objects and methods
across the reference
doc.
20. Problem 3: Lack of ownership
Auto-doc is a
stray dog.
Auto-doc is owned
like a stray dog or wiki
is owned. Someone
may contribute some
food or a page
without care for the
whole. Usually there
isn’t a developer
overseeing all the
doc. Tech writers feel
less responsible when
auto-doc is a separate
from their output.
21. Problem 4: Doesn’t integrate
Auto-doc doesn’t
integrate directly into
a website except as a
link from your other
web pages. Like a
HAT-produced
webhelp file, the
auto-doc is its own
little website.
22. Problem 5: Gives illusion of real doc
“… auto-generated
documentation is worse than
useless: it lets maintainers fool
themselves into thinking they
have documentation, thus
putting off actually writing good
reference by hand. If you don’t
have documentation just admit
to it. Maybe a volunteer will
offer to write some! But don’t
lie and give me that auto-documentation
crap”. – Jacob
Kaplan Moss
Looks real but
isn’t.
23. Question: Would
merging auto-doc
with regular doc
help solve
integration and
ownership issues?
24. Merge option 1: Leverage DITA to pull
source doc into tech comm tools
You run the Docfacto
DITA doclet inside
Eclipse just like
Javadoc, but you
select a custom DITA
Doclet. Files get
converted to
reference topic
types. With Docfacto
Links, you can add
links to and from in-source
files.
25. Merge option 2: Abandon tech comm
tools for dev tools that use markdown
26. “… It reminds me of back in the day when I
was a photographer. So many of my
colleagues were wrapped up in the
technology, they forgot the original purpose
was to create a photograph. Same with
document generators. We are debating
whether it's better to generate docs from
source comments than an alternative. My
point is that this debate is a red herring. It's
not where you put the information, it's the
quality of the information.”
– Doug Schwartz
27.
28. REST API basics
URLs requests return specific data HTTP Request
Response
29. Responses in JSON or XML
Configuration
parameters
Response in JSON format
31. cURL calls
HTTP requests are often demonstrated through
cURL calls, with different HTTP methods:
GET – retrieve
POST – edit
PUT – create
DELETE – remove
32. No auto-doc with REST APIs because
source language varies so much
“The beauty of Web APIs is that they can be written in
whatever language you like and in whatever manner you
like. As long as when an HTTP request comes in, the proper
HTTP response goes out, it doesn't matter how it actually
happens on the server. But this very flexibility makes
automated documentation nearly impossible, since there's
no standard mapping between what an API request is and
what the code is that generates its response.”
-- Kin Lane, APIevangelist.com
33. But REST APIs have some endpoint
generator possibilities, with Swagger
Generates an endpoint
based on values you
enter
37. Sample REST API doc sites
Many API doc sites
are modern looking
and awesome.
Remember, the API
Doc is the product
interface, so it has
to look good.
53. 10 non-trends
1. PDF output
2. Collapsible sections
3. Short pages
4. Multiple outputs of content for different audiences
5. DITA or XML authoring models
6. EPUB and mobile formats
7. Comments on pages
8. Wikis
9. Tripane webhelp files
10. Video tutorials
56. How do you merge worlds?
Is it possible to
merge tech comm
and API doc worlds,
or are they too
different?
57. Import DITA into WordPress (Pros)
Pros
- Easy to build and theme a beautiful site.
- Create a network of sites controlled from a single point.
- Imports DITA flawlessly.
- Include additional functionality (e.g., forums, Q&A).
- Leverage existing plugins (auto-toc, jQuery menus, live
search).
- Easily hire out branding and code development.
- Works with a lot of different systems (30,000 + plugins).
- Dynamically serve conditional content to users.
- Allow threaded comments (SME review, user feedback).
- Include other content outside of doc (mktg., kb articles)
- Much better analytics (e.g., see search queries on dashbrd)
58. Import DITA into WordPress (Cons)
Cons
- Database model is slower than static files.
- Import process isn’t a one-click job.
- Requires MySQL, PHP, and Apache architecture.
- May be problematic to integrate authentication with
another system (e.g., Salesforce).
- Regularly importing static files into a dynamic system may
be subverting the fundamental design of WordPress.
- May not be robust enough for massive doc projects.
60. Image Credits
• Slide 2: Mars, once. By Kevin Dooley. http://bit.ly/ZFYI0T
• Slide 4: 10 Reasons Developers Hate Your API (and what to do about it). By John Musser.
Slideshare. http://slidesha.re/1pnnDRf
• Slide 9. Spinning gears. By Brent 2.0. Flickr. http://bit.ly/1DexWM0
• Slide 10. Lolcat Generator: Can haz posters? http://bighugelabs.com/lolcat.php
• Slide 11. Code sample pulled from
http://www.docjar.net/html/api/java/util/Collections.java.html.
• Slide 16. Continental Drift. Wikipedia. http://en.wikipedia.org/wiki/Continental_drift
• Slide 17: Biodiversity fail. By Martin Sharma. Flickr. http://bit.ly/1CodnKM
• Slide 18. The Source of Bad Writing. Wall Street Journal. http://online.wsj.com/articles/the-cause-
of-bad-writing-1411660188
• Slide 19. Stray dog. By Jose Javier Perez Arenas. Flickr. http://bit.ly/1wau5NK
• Slide 22. The false. By Cristopher Cotrell. Flickr. http://bit.ly/1F1et36. Quote from Jacob
Kaplan Moss here: http://jacobian.org/writing/what-to-write/
• Slide 23 and 54. Finger face with question. By Tsahi Levent-Levi. http://bit.ly/1sWdnln
• Slide 32. Kin Lane, apievangelist.com. http://apievangelist.com/2012/03/08/automated-documentation-
for-rest-apis/
• Slide 37. Catwoman. http://bit.ly/11qDsNU
• Slide 56. Nasa, new eyes: Butterfly. http://bit.ly/1u7ANzE
Another source: “Auto-generated documentation that documents each API end-point directly from source code have their place (e.g., its great for team that built the API and its great for a reference document) but hand-crafted quality documentation that walks you through a use case for the API is invaluable. It should tell you about the key end-points that are needed for solving a particular problem and it should provide you with code samples.” https://communities.cisco.com/community/developer/blog/2014/09/03/introducing-devnet-slate
Also enunciate http://enunciate.codehaus.org/ and https://github.com/mashery/iodocs