I'd Rather Be Writing
I'd Rather Be Writing
  • Video 60
  • Views 80 866
Best practices in API docs: Product overviews and getting started tutorials
For new users, two of the most important topics in API docs are the product overview and getting started tutorial. These two topics combine conceptual understanding with hands-on exploration. Together, these topics can ground users in a good understanding of your product and the confidence to implement it.

However, both of these topics are challenging. The product overview requires solid understanding of the whole product, described succinctly and clearly. Its content can overlap with marketing content and often has both engineering and business executive audiences. The getting started tutorial requires writers to handle an intricate balance of information - keeping the instructions brief ...
Views: 410

Video

Biking along Cedar River Trail
Views 422 months ago
The view along the Cedar River Trail in Washington, near Maple Valley. tinyurl.com/32fewv4t. See my blog for more about me: idratherbewriting.com
Biking in Seattle down 2nd Ave in the protected two-way bike lane
Views 963 months ago
Biking in Seattle down 2nd Ave in the protected two-way bike lane
Tech comm and marketing: How to make your tech comm group more visible to those within your company
Views 1414 months ago
Because docs are used by so many groups within an organization (training, support, solutions engineers, marketing, and more), documentation should be a central part of an organization's content strategy. However, reuse of documentation content across these groups can be problematic. Additionally, marketing groups can misinterpret the type of content that actually builds relationships with users...
Product overviews vs. getting started tutorials - striking a balance
Views 2795 months ago
This is a recording of a presentation I gave titled "Product overviews vs. getting started tutorials - striking a balance between read-first and try-first user behaviors" on July 27, 2021, to tekom europe as a webinar. Here's the summary: This presentation focuses on balancing action with narration: How to find the right balance between action-oriented task writing and big picture narrative pro...
Micro content and Flare - Conversation with Kate Schneider
Views 2579 months ago
In this podcast/videocast, I chat with Kate Schneider about micro content and Flare. Kate shares micro content examples from her current documentation and explains the strategies she considers when creating micro content. She shows specifically how to leverage analytics in determining micro content topics. Learn more here: idratherbewriting.com/blog/micro-content-and-flare-conversation-with-kat...
San Tomas Aquino Trail - riding to work
Views 85Year ago
San Tomas Aquino Trail - riding to work
San Tomas Aquino Trail - riding back from work
Views 34Year ago
San Tomas Aquino Trail
Guadalupe River Trail, San Jose
Views 218Year ago
Guadalupe River Trail, San Jose
Sample uploading of images via AWS CLI with Wasabit
Views 63Year ago
Sample uploading of images via AWS CLI with Wasabit
Blurring the lines between content and product design -- interview with Jonathon Colman
Views 183Year ago
Blurring the lines between content and product design interview with Jonathon Colman
A tip for doc reviews -- bring a list of questions
Views 232Year ago
A tip for doc reviews bring a list of questions
Writing productivity tip: Focus sessions
Views 238Year ago
Writing productivity tip: Focus sessions
Developer Portal Strategies for Complex Landscapes -- conversation with Kristof van Tomme
Views 107Year ago
Recently I chatted with Kristof van Tomme, CEO and co-founder of Pronovix, about a topic that's increasingly relevant in the past several months: how to deal with complex, rapidly evolving landscapes. Specifically, we focus on developer portal strategies that involve finding a balance between constraints and freedom to innovate, between providing a coherent story and letting implement your API ...
devdoctrendswebinar
Views 1.1KYear ago
I recently gave a webinar on trends in developer docs to the STC Washington DC chapter on March 12, 2020. In this presentation, I presented the results and analysis of my Trends in Developer Documentation 2020 survey. See idratherbewriting.com/blog/upcoming-webinar-trends-api-docs-differ-from-other-trends/ for details. Here's more info about the webinar: ABOUT THE WEBINAR Do you have an interes...
Intro to API documentation
Views 1.9KYear ago
Intro to API documentation
Tech comm trends: Providing value as a generalist in a sea of specialists
Views 6612 years ago
Tech comm trends: Providing value as a generalist in a sea of specialists
Intro to API Documentation
Views 26K2 years ago
Intro to API Documentation
API Documentation Workshop (Raleigh): Video 5 of 5
Views 1.6K2 years ago
API Documentation Workshop (Raleigh): Video 5 of 5
API Documentation Workshop (Raleigh): Video 4 of 5
Views 1.4K2 years ago
API Documentation Workshop (Raleigh): Video 4 of 5
API Documentation Workshop (Raleigh): Video 3 of 5
Views 2.2K2 years ago
API Documentation Workshop (Raleigh): Video 3 of 5
API Documentation Workshop (Raleigh): Video 2 of 5
Views 3.1K2 years ago
API Documentation Workshop (Raleigh): Video 2 of 5
API Documentation Workshop (Raleigh): Video 1 of 5
Views 6K2 years ago
API Documentation Workshop (Raleigh): Video 1 of 5
Tech Comm Trends: Providing Value as a Generalist in a Sea of Specialists
Views 1302 years ago
Tech Comm Trends: Providing Value as a Generalist in a Sea of Specialists
What went wrong -- clip from Travelers (episode 10)
Views 1383 years ago
What went wrong clip from Travelers (episode 10)
API Documentation Workshop: Video 5 of 5 (Menlo Park)
Views 3343 years ago
API Documentation Workshop: Video 5 of 5 (Menlo Park)
API Documentation Workshop: Video 4 of 5 (Menlo Park)
Views 3773 years ago
API Documentation Workshop: Video 4 of 5 (Menlo Park)
API Documentation Workshop: Video 2 of 5 (Menlo Park)
Views 8133 years ago
API Documentation Workshop: Video 2 of 5 (Menlo Park)
API Documentation Workshop: Video 3 of 5 (Menlo Park)
Views 4303 years ago
API Documentation Workshop: Video 3 of 5 (Menlo Park)
API Documentation Workshop: Video 1 of 5 (Menlo Park)
Views 3.7K3 years ago
API Documentation Workshop: Video 1 of 5 (Menlo Park)
Intro to API Documentation
Views 26K2 years ago
Intro to API Documentation
Intro to API Documentation
Views 12K4 years ago
Intro to API Documentation
API Documentation Workshop (Raleigh): Video 1 of 5
Views 6K2 years ago
API Documentation Workshop (Raleigh): Video 1 of 5
Docs as code tools and workflows presentation
Views 4.3K3 years ago
Docs as code tools and workflows presentation
Generate JSON automatically with Stoplight
Views 4.1K3 years ago
Generate JSON automatically with Stoplight
API Documentation Workshop: Video 1 of 5 (Menlo Park)
Views 3.7K3 years ago
API Documentation Workshop: Video 1 of 5 (Menlo Park)
API Documentation Workshop: Part I of III
Views 3.2K3 years ago
API Documentation Workshop: Part I of III
OpenAPI and Swagger
Views 3.1K3 years ago
OpenAPI and Swagger
API Documentation Workshop (Raleigh): Video 2 of 5
Views 3.1K2 years ago
API Documentation Workshop (Raleigh): Video 2 of 5
API Documentation Workshop (Raleigh): Video 3 of 5
Views 2.2K2 years ago
API Documentation Workshop (Raleigh): Video 3 of 5
Intro to API documentation
Views 1.9KYear ago
Intro to API documentation
API Documentation Workshop (Raleigh): Video 5 of 5
Views 1.6K2 years ago
API Documentation Workshop (Raleigh): Video 5 of 5
API Documentation Workshop (Raleigh): Video 4 of 5
Views 1.4K2 years ago
API Documentation Workshop (Raleigh): Video 4 of 5
API Documentation Workshop: Part II of III (Denver)
Views 1.2K3 years ago
API Documentation Workshop: Part II of III (Denver)
devdoctrendswebinar
Views 1.1KYear ago
I recently gave a webinar on trends in developer docs to the STC Washington DC chapter on March 12, 2020. In this presentation, I presented the results and analysis of my Trends in Developer Documentation 2020 survey. See idratherbewriting.com/blog/upcoming-webinar-trends-api-docs-differ-from-other-trends/ for details. Here's more info about the webinar: ABOUT THE WEBINAR Do you have an interes...
Stoplight: Work in both Design and Code views
Views 1K3 years ago
Stoplight: Work in both Design and Code views
API Documentation Workshop: Video 2 of 5 (Menlo Park)
Views 8133 years ago
API Documentation Workshop: Video 2 of 5 (Menlo Park)
Tech comm trends: Providing value as a generalist in a sea of specialists
Views 6612 years ago
Tech comm trends: Providing value as a generalist in a sea of specialists
API Documentation Workshop: Part III of III (Denver)
Views 5793 years ago
API Documentation Workshop: Part III of III (Denver)
API Documentation Workshop: Video 3 of 5 (Menlo Park)
Views 4303 years ago
API Documentation Workshop: Video 3 of 5 (Menlo Park)
Best practices in API docs: Product overviews and getting started tutorials
Views 4102 months ago
For new users, two of the most important topics in API docs are the product overview and getting started tutorial. These two topics combine conceptual understanding with hands-on exploration. Together, these topics can ground users in a good understanding of your product and the confidence to implement it. However, both of these topics are challenging. The product overview requires solid unders...
API Documentation Workshop: Video 4 of 5 (Menlo Park)
Views 3773 years ago
API Documentation Workshop: Video 4 of 5 (Menlo Park)
API Documentation Workshop: Video 5 of 5 (Menlo Park)
Views 3343 years ago
API Documentation Workshop: Video 5 of 5 (Menlo Park)
Product overviews vs. getting started tutorials - striking a balance
Views 2795 months ago
This is a recording of a presentation I gave titled "Product overviews vs. getting started tutorials - striking a balance between read-first and try-first user behaviors" on July 27, 2021, to tekom europe as a webinar. Here's the summary: This presentation focuses on balancing action with narration: How to find the right balance between action-oriented task writing and big picture narrative pro...
Micro content and Flare - Conversation with Kate Schneider
Views 2579 months ago
In this podcast/videocast, I chat with Kate Schneider about micro content and Flare. Kate shares micro content examples from her current documentation and explains the strategies she considers when creating micro content. She shows specifically how to leverage analytics in determining micro content topics. Learn more here: idratherbewriting.com/blog/micro-content-and-flare-conversation-with-kat...
Writing productivity tip: Focus sessions
Views 238Year ago
Writing productivity tip: Focus sessions
A tip for doc reviews -- bring a list of questions
Views 232Year ago
A tip for doc reviews bring a list of questions
Guadalupe River Trail, San Jose
Views 218Year ago
Guadalupe River Trail, San Jose
Blurring the lines between content and product design -- interview with Jonathon Colman
Views 183Year ago
Blurring the lines between content and product design interview with Jonathon Colman
Tech comm and marketing: How to make your tech comm group more visible to those within your company
Views 1414 months ago
Because docs are used by so many groups within an organization (training, support, solutions engineers, marketing, and more), documentation should be a central part of an organization's content strategy. However, reuse of documentation content across these groups can be problematic. Additionally, marketing groups can misinterpret the type of content that actually builds relationships with users...

Comments

  • bpotter136
    bpotter136 23 days ago

    Great intro into API Documentation. Thank you.

  • Artem
    Artem Month ago

    Thanks šŸ‘

  • SUSHMA.N GUPTA
    SUSHMA.N GUPTA 3 months ago

    Good learning for a beginner !

  • Deep Gandhi
    Deep Gandhi 3 months ago

    1) Suppose, I have a schema for Project model which contains 20 properties. Now for my project-dropdown API I only need 3 properties from the schema then how I can refer the schema and pick few properties only? 2) I have 2 schemas, one for Project with 20 properties and another one is Task with 10 properties. Now for ProjectDetails API I have response something like { id: 1, name: "ProjectName", tasks: [ {id: 1, name: "TaskName"} ] } Now how I can accomplish this nested object by referring both individual schema which are Project and Task 3) Can I have search box in Swagger UI to filter APIs?

  • TransLinguist
    TransLinguist 3 months ago

    The best intro i have seen.

  • fungo44
    fungo44 4 months ago

    Very interesting Tom

  • Ruchira Joshi
    Ruchira Joshi 5 months ago

    By product overview do you mean the whole web page given on websites in product section?? Or one particular section in guides that we write??

  • Rishabh
    Rishabh 5 months ago

    San tomas and guadalupe trail on a full moon is very pleasing and calming. Whats the soundtrack?

  • LernenInVerschiedenenFormen

    I wonder if there is more dev in this area nowadays. The git approach seems very, very tedious and slow. A multi-user online editor like google docs seems to be a much faster approach.

  • Michael Roberts
    Michael Roberts 8 months ago

    This is an awesome lecture. Thanks for uploading.

  • Alex L
    Alex L 8 months ago

    Great learning material! Thanks for your work Tom.

  • Shynie
    Shynie 9 months ago

    I am your 600th sub x'D

  • Fredrik T
    Fredrik T Year ago

    Too long for the content it provided. Just like an API a presentation is perfected ones everything not needed is removed.

  • Garima Srivastava

    This is what i was looking for, clear and crisp info about API documentation. Thanks

  • Anon
    Anon Year ago

    Do you need to be able to retain a lot of information (the answers to the questions)? Or can u record them or have them email u

  • Datta Vanare
    Datta Vanare Year ago

    Very useful.. Thanks šŸ‘

  • Yunjie Hong
    Yunjie Hong Year ago

    What is STC?

    • K Hill
      K Hill Year ago

      Society for Technical Communications

  • kaushani sen
    kaushani sen 2 years ago

    Great video on API documentation. I have been following your blogs as well, the content for Technical Writing is so up to date with recent trends. Recently, I was looking for Technical Writing trends 2020, came across Instruction Manuals with GIF as a trend. I would love to see some examples of it on your blog!

  • Tammy Butcher
    Tammy Butcher 2 years ago

    Hi Tom. Great intro. I've been taking a few bootcamp courses and here is what I find frustrating in those and in this course (and in API docs in general). You have us use the By city name endpoint for the open weather API which (it would seem) queries cit name or city name and country code. And yet, in Postman, you then enter zip, units (somehow knowing to use imperial), and appid. How do you know to enter this? I looked all through the docs and see nowhere that this info is specified yet, somehow, you knew to enter this specifically. For those of us that are new to this, how would we find this information?

    • Tom Johnson
      Tom Johnson 2 years ago

      I think I am simply implementing some of the required parameters specified in the doc, though I might not have explained where in the doc those parameters are specified. The OpenWeatherMap docs aren't the greatest example -- the API just seemed like a stable one.

  • Paul Harker
    Paul Harker 2 years ago

    Absolutely brilliant top-level overview of what's required in good API documentation. Thanks for uploading.

  • FsocietyEarth
    FsocietyEarth 2 years ago

    Hi, is it possible to start tech writing carrier with API documentation?

    • FsocietyEarth
      FsocietyEarth 2 years ago

      @Tom Johnson Thanks a lot for your valuable response Sir!!, Need a help from you could you suggest directly jumping to AIP documentation would be okey or I need to find the entrance door? Little confuse as waisted 3-4 years in doing various things. I have heard and read a lot about you and your unique website especially website name. Or you have video or pdf guide for starters please share, It will be helpful for me and your fans šŸ‘£.

    • Tom Johnson
      Tom Johnson 2 years ago

      sure, if you have strong tech skills and know how to write, and can prove it with a portfolio, you can surely get your foot in the door somewhere.

  • Ali Jann
    Ali Jann 2 years ago

    Iā€™m 19 minutes in and that overview of looking through APIs from a developers perspective was soooo helpful. I am going to continue watching jow

  • Amit Rajput
    Amit Rajput 2 years ago

    Thanks a bunch this was so helpful

  • casmcctutube
    casmcctutube 2 years ago

    hi i don't know if anyone can help me but when i click 'example' it shows the code all smushed together. It's not formatted in a singular column. It looks like just one big hulking paragraph of code

    • casmcctutube
      casmcctutube 2 years ago

      @Tom Johnson hey thanks for responding! I actually didn't have JSON formatter so the code was 'ugly' heheh

    • Tom Johnson
      Tom Johnson 2 years ago

      maybe the code is minified? is there a "prettify" option?

  • Dibya ranjan
    Dibya ranjan 3 years ago

    Great learning curve!

  • Nitesh Agrawal
    Nitesh Agrawal 3 years ago

    One of the best and most informative videos I have ever seen on TheXvid.

  • Lord Gates
    Lord Gates 3 years ago

    Great video. Try not to suck on your tongue when you start new sentences. It gets grating after a while.

  • Vincent Chen
    Vincent Chen 3 years ago

    The video itself is awesome. But some audiences asked some real dump questions, which are a bit annoying.

    • Anubha S
      Anubha S 2 years ago

      you mean *dumb?

    • Prathew Raj
      Prathew Raj 2 years ago

      Exactly! Wasted so much of time to ask/tell close to nothing! Presenter was just being humble.

  • Kurt N. Heiss
    Kurt N. Heiss 3 years ago

    Awesome overview and description of providing API information - highly recommended!