Re: Documenting .Net APIs

Subject: Re: Documenting .Net APIs
From: Ryan Young <ryangyoung -at- gmail -dot- com>
To: Tony Chung <tonyc -at- tonychung -dot- ca>
Date: Tue, 23 Jun 2015 15:23:51 -0700

I've also heard Stripe cited as a prime example of API docs. Other examples
that people seem to like are Square
<https://docs.connect.squareup.com/#get-payments> and Twilio
<https://www.twilio.com/docs/api>. You might want to take a look Swagger's
example API docs <http://petstore.swagger.io/>, too.

I've only documented RESTful APIs, but the important things for those are
the endpoints (where do I send my request?), the request (is it a POST,
GET, PUT? Is it just a HTTP call or do I need to include a JSON body? what
are the parameters?), and the response (what is this thing I got back?).

I'm not sure if it would with your situation, but Postman
<https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en>
is a great tool for testing and using (REST) APIs.

On Tue, Jun 23, 2015 at 1:29 PM, Tony Chung <tonyc -at- tonychung -dot- ca> wrote:

> One company I spoke with cited stripe.com 's API doc as an example to
> beat.
> Then again, everyone's got an API. That's what the cool kids are doing.
>
> -Tony
>
> On Tuesday, June 23, 2015, Chris Morton <salt -dot- morton -at- gmail -dot- com> wrote:
>
> > Hi all,
> >
> > Although I've been a techwriter for over 25 years, I've never documented
> > APIs. I also have zero familiarity with .Net and C# programming.
> >
> > But now I have to take a test and only have 44 hours left to complete the
> > assignment. It's a blog post to instruct ABC app developers how to use
> XYZ
> > company's API set as part of their (ABC's) own custom deployment to XYZ's
> > cloud platform.
> >
> > - XYZ's platform is for both Windows and Unix.
> > - I've looked at a sample XYZ API set, full of .cs, .xml, and config
> > files.
> >
> > Obviously Windows users can make use of Visual Studio (VS), and it
> appears
> > that there is a VS Unix counterpart. Is this correct?
> >
> > How might you proceed with this assignment, given the running clock?
> >
> > Thanks
> >
> > > Chris
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Learn more about Adobe Technical Communication Suite (2015 Release) |
> > http://bit.ly/1FR7zNW
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as tonyc -at- tonychung -dot- ca
> > <javascript:;>.
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com <javascript:;>
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com <javascript:;>.
> Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> >
> > Looking for articles on Technical Communications? Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our public
> > email archives @ http://techwr-l.com/archives
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Learn more about Adobe Technical Communication Suite (2015 Release) |
> http://bit.ly/1FR7zNW
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as ryangyoung -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn more about Adobe Technical Communication Suite (2015 Release) | http://bit.ly/1FR7zNW

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Documenting .Net APIs: From: Chris Morton
Re: Documenting .Net APIs: From: Tony Chung

Previous by Author: Re: Politically correct term for four-eyes authorization?
Next by Author: Re: "The World of Technical Communication and Writing"
Previous by Thread: Re: Documenting .Net APIs
Next by Thread: Re: Documenting .Net APIs


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads