How To Write a How To

DavidZemon

The title is a hair misleading but I thought it was fun

I'm looking for examples of software documentation websites (which include API docs as one part) that are really good. I'm currently in the process of revamping PropWare's documentation and I need some examples to start with.

About my only limitation is that it (my own website, not your example) has to be done with Doxygen. Doxygen is reasonably flexible, so I don't think that will limit me too significantly. I only mention it because I don't want someone jumping in and saying "I really like the format that ___ provides! You should just use that instead!" I can certainly work to mimic that framework, but I won't be jumping ship off Doxygen unless there's another tool out there that is compatible with Doxygen's source code markup.

And the other thing is, I don't care about CSS just yet. Colors, font size, etc can all come later.

DavidZemon

I'm starting out with Doxygen's own website: http://www.stack.nl/~dimitri/doxygen/index.html. it's alright, but there's so much content that I get lost pretty quickly when I'm browsing it and usually have to revert back to Google when I need to find something on the site.

DavidZemon

Arduino! Of course! I've always thought their website was good...

I'm stealing their Getting Started outline now
https://www.arduino.cc/en/Guide/HomePage

Heater.

I don't know how this fits in with doxygen, haven't used doxygen in years, but I really like the documentation of the stormpath.com APIs. It's comprehensive and very clear.

For every class and method they have clearly documented constructors, signatures, options etc. All the parameters and returns nicely described. A clear description of what it is for and what it does. And, importantly, examples of usage.

For example have a look at the page for the stormpath client object. A thing of beauty.

Notice the index on the left hand side of the page. Makes everything you want easily findable.

JasonDorie

One of the things programmers often miss is the big picture. I can often understand the specifics of small functions just by looking at them, but how everything fits together, where to start, high-level overviews, design decisions, etc are often lacking. Don't document the obvious - document what isn't.

DavidZemon

At very least, the client API doc is very good
http://docs.stormpath.com/java/apidocs/com/stormpath/sdk/client/Client.html

As good if not better than the Oracle Java docs that I've poked through. It's a lot more detail at the class level than I'm providing for any of my own classes (though I think my method-level documentation is on par). I think reaching that level of detail for all classes is a good goal - thanks for the pointer.

The rest of their website (starting with stormpath.com) is reasonable. There is so much going on though, I had a lot of trouble finding that specific page.

I also edited my original post. I realized my previous words made it sound like I was only looking for API examples, when I'm really looking for whole-site examples. My API docs are pretty good (I think...), but my site-level organization is "lacking" to say the least.

Heater.

Ah yes, the big picture and the whole site.

I actually think the stormpath site is brilliant in that respect.

I start here: https://stormpath.com/ That tells me succinctly what they are about.

I hit "docs" in the nav bar and get to here: https://docs.stormpath.com/home/

They have docs for a ton of languages and frameworks laid out nicely. I'm using node.js so I hit the "node" button and end up here: http://docs.stormpath.com/nodejs/

I don't want to use any framework or library, I want to write my own code. So I look at the generic node panel.

There I see a link to a quickstart guide http://docs.stormpath.com/nodejs/quickstart/ so I go there. It walks you by the hand through building storm path authentication from scratch. Very clear, easy to follow, and works. Yes I did that initially.

Having got the big picture and the confidence of something working I go back and select the API Reference link:

Boom! I'm here http://docs.stormpath.com/nodejs/api/home where the whole API is a breeze to explore and/or refer to when needed.

A thing of beauty.

DavidZemon

ah, that seems like an easy path

I just found someone has already bootstrap-ified doxygen, so that should make the CSS a lot better.
https://github.com/Velron/doxygen-bootstrapped

DavidZemon

Okay, what do you think of http://david.zemon.name/PropWare now? It's been completely reorganized and large parts have been re-written.