Identify good examples of API documentation

[oubiwann]

In the same vein as issue #36 (but with a less immediate need), we should build a list of top-notch programming language, framework, and library docs:

• what makes them good?
• how might a given approach be adopted to LFE?
  • how about third-party, community LFE libraries?

Some examples that come to mind:

• Python: nothing fancy, but rock-solid for nigh two decades
• OpenStack: Anne Gentle has done an amazing job with this massive, massive project
• Some bits of the Django docs, since I'm a firm believer in showing code in the docs (though this does introduce a phenomenal maintenance burden, unless you get clever with your docs infrastructure...)
• I've heard good things about MSDN, but maybe I need more familiarity with it before I see its greatness
• I hated Amazon's AWS API docs initially, but have grown quite fond of them over the years (and with improvements)

Please share your favourites!

Part of the Planning Epic.

[arpunk]

I've always been fond of Hackage and QuickDocs. Seems QuickDocs is offline at the moment (cached copy).

Hackage links into your dependencies documentation, it shows you the types and can even link images. Some folks even generate images using some sort of ascii->png tool and embed it into the docstring.

Having code samples in documentation is a huge win.

Maybe LFE should have it's own wrapper to EDoc? Maybe something new that gathers from the different docstrings and parses them into a nice format? Shipping with up-to-date docs (including dialyzer types annotations) should be encouraged.

[oubiwann]

I've been looking at projects like Read The Docs (Sphinx-based, uses ReST instead of Markdown ... not good for us, but pretty good overall API docs site features) and I haven't yet found anything that really grabs me.

The Github Documentation site is actually the most impressive I've seen so far:

• https://developer.github.com/v3/

They blogged about how they're now supporting versioned docs (which we will need) with the latest Jekyll and the release of their new site: How GitHub uses GitHub to document GitHub. They've open-sourced their site here:

• https://github.com/github/developer.github.com

I'm going to try to get a copy of it running and see how we might adapt it for LFE. Our stuff is already in markdown (all the sites as well as all the Gitbooks), and we use Jekyll already for the docs site and the blog, so this might be the best place to start for now ...

[oubiwann]

@arpunk: I've been thinking more about your example of http://quickdocs.org/ ... this is one facet of what I'd like for docs.lfe.io to provide. Maybe through a combination of:

• projects adding documentation metadata to a project file
• LFE projects generating their API docs with lodox and maybe user guides with Slate or some such.
• the software we use to generate docs.lfe.io could then check all the projects in a set "approved" (read: searched/known) Github orgs (e.g., lfe, lfex, lfe-rebar3, quasiquoting, etc.) and for all projects that have a configuration file with the appropriate project documentation metadata would then get included in a part of the docs.lfe.io site ... something very similar to what http://quickdocs.org/ is ...

[oubiwann]

Something else that I've been looking at lately for higher-level project organization is the work that the OpenStack community has done with http://docs.openstack.org/ ... in particular the intuitively obvious category-level organization below the fold on that site (this ticket is exploring that work in the context of an LFE docs site: lfe-deprecated/docs3#2).

[yurrriq]

The LFE compiler is soon to get a whole lot better at handling docs. We're going to write a beam chunk (for now) called "LDoc" with a property list of doc records, similar to the shape of Lodox data currently. I'm away from my keyboard now, but my get it wrapped up nicely as soon as tonight. The relevant issue is lfe/lfe#211.

[oubiwann]

This ticket is actually focused on a different aspect of "API Documentation" -- not the automatic generation of content based upon code, etc., but rather the organization and presentation of API documents to the end user/reader.

In other words, regardless of the internal mechanisms used to document actual code and transform that into documents, an over-arching organization of all the API docs we provide on docs.lfe.io needs to be addressed. The latest mockups for v3 of the site are exploring this organization.

[oubiwann]

Calling this one done -- but feel free to add anything useful that you come across. This ticket will remain linked to others, and continue to provide the source of information needed to evaluate good examples.