4.0 EventBrite example

Activity

4.1: Flickr example

Activity

4.2 Klout example

Activity

Use the Klout API to get your Klout score and a list of your influencers and influencees.

4.3 Aeris Weather Example

Activity

Use the Aeris Weather API to get the wind speed (MPH) for a specific place (your choice).

4.4 Moving on to Publishing API docs

Hooray! You finished the documenting APIs part of the course! Now, on to publishing API docs.

4.5 Publishing API doc

Why devs don't use HATs

No integration into version control

No auto-generation of doc from source

No reference templating engines

No interactive API consoles

No sexy outputs that sell

4.6 List of 100 APIs

Programmable Web

Activity

Look at about 5 different APIs from the list on "4.6 List of 100 APIs." Identify one thing that the APIs have in common.

4.6 Breaking down API doc

Guides

Reference

Tutorials

4.8 Tool decisions

Who will write? Engineers or tech writers?

Pros of having engineers write...

Cons of having engineers write...

4.9 Github wikis

Collaboration platform

Activity

Following the instructions in 4.9, do the following:

Create a Github wiki and publish content on a sample page.

Save the Github repository locally.

Make a change locally, commit it, and push the commit to the Github repository.

5.0 More about Markdown

Sample syntax

## Heading 2
This is a bulleted list:
* first item
* second item
* third item
This is a numbered list:
1. Click this **button**.
2. Go to [this site](http://www.example.com).
3. See this image:
![My alt tag](myimagefile.png)

For a detailed example, see the code sample on 5.0.

Activity

On your Github wiki page, edit the page and create the following:

level 2 heading

numbered list

bulleted list

bold word

code sample with html highlighting

table

5.1 Using a version control system

Github and social coding

5.2 Pull request workflows

Merging branches

5.3 REST API specification formats

Swagger

RAML

API Blueprint

5.4 Swagger

Sample output

Activity

Follow the instructions in 5.4 to create a Swagger output using the information from the Mashape Weather API.

link tags

/**
* First paragraph.
*

* Link to a class named 'Foo': {@link Foo}.
* Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}.
* Link to a method 'baz' on this class: {@link #baz}.
* Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
* Link to a method handling method overload {@link Foo#bar(String,int)}.
*/
public ...

Previewing Javadoc comments

7.6 Exploring the Javadoc output

7.7 Doxygen

Front-end GUI generator

Doxygen output sample

7.8 Creating non-ref docs with native library APIs

… 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