Clear and simple API documentation

No Comments

Looking for API documentation you can understand without 20 years of programming under your belt?

API Documentation That Makes Sense!

Note: This post is “Sticky” so, new posts appear below this one.

The purpose of apiDocumentation.com is to generate practical document for API end users.

The fundamental problem we are solving is simple. We are bridging the gap between API engineers and API end users (software developers).

Initially our journey through learning the practical use of the iPhone and iPad APIs are what I plan to document, but I welcome anyone else who would like to show off their skills by documenting other APIs.

What APIs are being documented here and who is doing it?

The goal of this site is to provide a collaboration point for people who enjoy developing software with specific APIs.

These humble beginnings start with my personal activity, but I’m hoping to find others, along the way, who want to share their interface knowledge, gain geek credibility, increase their reputation as a skilled developer, and create useful publications (and other content) based on their knowledge.

Any of a zillion APIs like the Android API, iPad API, iPhone API, Mac OS X APIs, WordPress API, Flickr API, Apache API, Digg API, DNS API, YouTube API, Google Maps API, Twitter API, or any other application programing interfaces available out there as a web-service or stand alone application API makes for great subject matter. They get perticularly exciting when you get them to interoperate with each other.

Really there are a lot of APIs out there so if you have an interest in helping others to learn how to use a specific API please feel free leave a comment and I’ll contact you to explain how you can personally benefit by contributing to this community.

This is pretty hard stuff… LOL

No Comments

Wow. This is hard stuff! But, anything worth doing…

As I embark on this Journey, I can see how painful it is to create documents while creating an application.

Never fear though, I have not lost heart… I’m just taking it slow…

This is a project that is well worth doing…

How To Profit From Your Applications (or anything else for that matter).

No Comments

Profit From Your Applications without being spammy or sleazy – Sound Theory or Just Smoke With No Fire?

A very good friend of mine asked me about having lunch with him to talk about the business model he wants to use to sell products online without being all “spammy” or “sleazy”. I dedicate this to you Cody.

Creating income from software is not a new thing. But many argue that market saturation or the condition of the economy really have an impact on your ability to make money on your applications.

Don’t be misled, markets are fickle. Today they love Microsoft (late 90′s) tomorrow they are not so sure (late 2010′s apple is all the rage.) The economy is bad but people are still buying what they want because tomorrow the economy may completely collapse.

With this in mind, here is a theory you can operate from… it will hopefully help you understand how you can generate income with your applications.

Success selling anything amounts to understanding some common laws of marketing.

I know… the LAST thing you probably want to hear about is marketing… But, in the end, if you want people to buy your application they will need to find it and when they find it you will need to help them understand HOW it will impact them. If you don’t take the time to figure out how to explain this well, people who NEED your application simply won’t buy it.

Regardless of the API you’re using, if you plan on charging for your application these ideas should help.

The first rule of selling anything – is that nobody talks about selling anything! (Tyler was right…)

Before talking about selling any product, it is really important to know that anything can be sold BUT, “nobody wants to hear your sales pitch”. And, I’m sure you don’t want to pitch sales “fluff” (because we all know it is BS) to the customers that would also be your friends…

With this remarkable piece of integrity in your pocket, you must ponder what is REALLY important.

If they want it, they will come…(Yes, “Field Of Dreams Was WRONG“, and so was Ralph Waldo Emerson And His Mouse Trap Theory!.)

Even BAD ideas and bad things are purchased and sold all the time. Heroin is sold to people who want it. Overpriced homes are sold to people who want them. Unhealthy food is sold to people who want it. And, jobs that sound like dream jobs (but are really just bottomless pits of time destruction) are sold to unsuspecting talent all the time. (No, I’m not jaded, and I’m not a victim! I just have to escape, without losing my life savings, dammit! Yeah Kurt, I know you know what I mean! And, I feel you my brother!)

The lesson here is simply that people want stuff… period…

It isn’t bad, it isn’t evil. People just want stuff, and it is as simple as that (don’t add to that or subtract from it). People want stuff, and needs for the most part are taken care of these days so we don’t have to kill each other to get the stuff we want.

Your good idea can be sold to people who want it, but everyone else really doesn’t care!

Jack Johnson talks about advertising interruptions best in this great song!

My buddy, Justin, is promoting his girlfriend who is an amazing musician and I believe he is working hard to find her audience. This is a clear example of a good idea that is moving toward selling very well. She went from 180, to 70, to something like 10 for San Diego musicians in the last few weeks. Good ideas are worth spreading, but they have to land on “good soil” so not everyone will want her music (or this site for that matter).

The “key” is finding and working with people who want it, not shoving it down someone’s throat who would rather be playing nintendo or xbox.

Argue with it all you want, the simple fact is even “total shit” is sold and even “total shit” is bought. (Home electronics are great examples of total shit being sold. Brian! Thanks for sharing this killer laugh with me. BWAHAHA!)

This is a truth you cannot avoid. (No matter how much you deny it.) Good stuff and bad stuff will sell, because people want “good” and people want “bad” (for what ever reason). Regardless of your ideas people will do what they want and you can capitalize on that, (as well as give people what they want).

On the serious side, here are the two most critical rules to follow, when describing anything you want to sell.

  1. Does your application fill a want? “Wants” are way cooler than “needs”. (“I want a Fast Ferrari” is a lot more fun, and motivational, than “I need a car”.)

    “I want to keep my plants alive on my vacation” is a much more likely what someone is thinking when they are in the market for an automated plant feeder. They are not likely searching for an “automated plant feeder” after all.

    Focusing on a “want” rather than a “need” is much more effective from a marketing perspective. People figure out how to buy what they want. As long as their basic needs (as in Maslow’s hierarchy of needs) are met all other “needs” are NOT “really” needs.

    YOU may think they are (because you want to sell something), but many will argue that what “you think” they need is pretty subjective. My, non-conformist, advice would be don’t try to create a “false need” just to inflate your product’s “sense of self”. Instead focus on the want that you’re product fills, it will be MUCH easier to sell.

    A good example of this is smoking:
    One could argue that people “need” to quit smoking. But people who “want” to smoke will do it. Ask yourself WHY they want to smoke and you could be like RJReynolds and sell cigarettes to anyone who wants them, even though they are classified as “bad”.

    Another example of this is financial accumen. One could argue that people “need” to learn how to manage their money better. The state of the American economy is overwhelming evidence that people don’t pay attention to this foundational “need”. Ask ourself WHY people would want to learn more about managing money well, and you will be able to sell this to anyone who wants to know how to master their own finances.

    Needs are subjective, but “wants” are marketable. So focusing on an application that people will want for “emotional reasons” is a much safer bet than one they need for “logical reasons”.

    I can’t think of how many advertisements that told me I “needed” to buy anti-virus software. In true form, I said I’ll skip the “need” and buy what I “want”. So my solution to the anti-virus dilemma was to escape it all together and use, unix, linux, or Apple Mac. (This is a great example of anti-virus companies trying to create an “artificial need”.)

    Emotion is all about “want”. Logic is all about “need”. And, like a champion boxer, emotion will win a lot more often than logic.

  2. This “emotional vs logical” concept ends up being the one-two punch you will need to help people understand the value of any application you create.

    When you write your description of your application, focusing on how your application helps both emotionally and logically makes for greater appeal.

    Here is an example:
    Does someone buy a car with air conditioning because they will die in their car without it? Or do they buy it to keep themselves cool on those traumatic commutes to and from work?

    If you wanted to sell an air conditioned car to someone who owned a car without one which sentence makes more sense to write?

    This car has powerful air-conditioning to keep you cool.

    Or

    This car has a SPECTRA PREMIUM A/C COMPRESSOR, NEW — With clutch; 100 percent factory run tested and endurance tested using endurance simulator to ensure optimum product performance; Manufactured under QS-9000, ISO 9002 certified quality systems to meet or exceed OEM specifications; Carefully packaged for product quality and installation.

    Notice the second tells more, but says less.

    If you have ever driven on a long miserable commute you know that you could really care less about he specs and more about the fact that it will work as you expect.

    This is a fundamental thing to remember when describing your fancy new application… how can it help someone? This is the question to answer in anything you create to help people understand why they should buy your application.

Reblog this post [with Zemanta]

OnlyWire Auto Syndication

No Comments

Auto Syndication Using OnlyWire

Image representing Zemanta as depicted in Crun...
Image via CrunchBase

I’ve been spending some time setting up accounts to syndicate my API documentation content. So far it is pretty cool.

I’m creating this post using a few new tools actually.

Onlywire’s posting tool, along with wordpress plugin and Zemanta which is supposed to find content that is related to what I’m typing about but so far hasn’t found a thing…

And as soon as I typed that a bunch of Zemanta content popped up… nothing about the iPhone API or the Facebook API or the Twitter API or the iPad API… gee I wonder how many times I can say API before something pops up….

OH! there it goes…

I see how it works now… pretty slick… OK I’m impressed. As you can see it created a bunch of links out of the content that I’m typing about… cool…

Reblog this post [with Zemanta]

iPhone SQLite3 Tutorial

2 Comments

A buddy of mine was following this tutorial and he mentioned it to me.

If you’re interested in working with SQLite at the raw database level (Rather than through the Xcode objectmodel user interface) this could be helpful.

iPhone Todo List Tutorial

Reblog this post [with Zemanta]

WordPress API

No Comments

Primer for my wordpress API pages docs

In prepararion for my docs on th wordpress API I decided to see if I could set up post publishing from my iPhone.

The wordpress application on the iPhone seems to work well enough. But it crashes when I go to create a new category.

I’m using it now to publish this blog post.

I’ll keep you posted when I start working with the docs!

Planning Your Application

No Comments

Don’t make the same mistake I made!

I posted a new page related to planning your application prior to writing any code.

I love this graphic, to me it says I yield to put thought into something. So it seem appropriate for the content.

The discussion outlines the application I will be creating in a tutorial that will lead us to discussions regarding different iPhone APIs.

A diagram of the user interactions and uses for the different views that make up the application is available to study in order to gain an understanding of why planning is so critical but not paralyzing.

Server Properties iPhone Application.

Engineering Docs Vs. User Docs

No Comments

What is the difference between practical user level documentation VS. engineering level documentation?

Well to be completely honest I have a fight to pick with most engineering level document authors (Often they are so steeped in the lingo of API architecture that, often, they no longer speak the language of the common people). If the documentation lingo is approachable, often examples are missing, or context is missing.

When documentation is bad its, more often than not, filled with lots of unnecessary explanation and plenty of theoretical jargon. It just leaves the reader confused with more questions than answers.

When it is good, readers have many “Ah-Ha!” moments. Epiphanies that make the message clear! That is what is important. That is really what we are shooting for. We aren’t just talking about having documents that are syntactically or grammatically correct… We are talking about documents that are measured by one thing. Do people who read them understand them?

We attempt to avoid droves of ten dollar words to explain simple concepts. This happens because the smart engineers who build the APIs for us “common folk” are very (VERY) abstract thinkers. This little bit of quirkiness makes them PERFECT to architect the APIs that will forge the foundation for amazing products.

Winning API architecture is the benefit we get from their genius. To often, however, we don’t understand the documentation they offer for us to learn how their object bundles are supposed to work. This happens because creating an API is a lot more fun than documenting the API.

This gap, that needs to be bridged, brings us to the goal here which is to create documents that are simple, clear, and easy to use in order to get something done.

The goal is to create usable and practical (dare I say, non-technical?) documents that can get someone on the ground and running quickly with an API that is new to them.

Here is an example: If you know how to use the wordpress API but you want to build an application on the iPhone, this site is here to help you understand the iPhone APIs as well as offer you a place to contribute your knowledge of the wordpress API to the world.

The documents here are meant to answer questions like:

What can I do with this object?

How can I do it?

What does an example look like?

Where does the example code usually go within the rest of my application?

Please read on below to see the latest blog posts or look a the menu on the right under the heading “What is on this site” to get an overview of the objects we have documented.

iPhone API Documents Added

2 Comments

In addition to adding a sticky post on the main page I’ve also added some pages to help get the ball rolling.

  1. I’ve added a new page to the site to begin the content related to the iPhone API. See the menu on the right hand side of the page or follow this link to our iPhone API Documentation Page.
  2. I’ve added a link to the iPhone Developer Community has been added to the menu links on the right also under the section “Other sites for API users”.
  3. And Finally I’ve added a new link to the UITableView object in the iPhone UIKit library/bundle to begin the documentation.

The ball is officially rolling, so I hope you subscribe to our API Documentation RSS Feed so you know when we are discussing objects of interest to you.

I’m looking forward to hearing from  you!

Data Recovery