Optimising docs for new users of pedestal

[gnarroway]

Hi there,

I've recently migrated our production systems to pedestal (from ring/jetty) after several attempts to digest all the documentation. I'm creating this issue to highlight some areas of the docs that could possibly be improved from the perspective of someone new to pedestal.

A concise getting started guide

Background

• the pedestal docs homepage lists the features of pedestal, but not really how to get started.
• there is a link to "get pedestal" from the pedestal GitHub, which lists a bunch of dependencies, some not being required. The "getting started" section on GitHub uses a lein template (not subsequently used in the docs) and then redirects back to pedestal docs, so we are back to square one.
• pedestal docs has a hello world but it is aimed at Clojure beginners and is overly verbose. For example, just understanding what dependencies you need is halfway down the page.

Proposal

• Modelled on the hapi home page, provide a direct link to "getting started", which is a concise guide covering:
  • installation (i.e. the basic dependencies)
  • starting a server
  • basic routing
• this is effectively an expanded version of the snippet on the pedestal docs homepage (with dependencies + some basic explanation), and makes it clear where to go next.

Alternatives

• Make the hello world guide more concise and retarget it at an audience who is a bit more familiar with Clojure. This may be reasonable as the default web stack for Clojure beginners seems to be ring/jetty these days, so by the time they get to pedestal, it is because they want something more.
• Rename the existing guide to "Hello world for Clojure beginners" and provide another more concise guide. I am not sure if that is what the crash course (linked from hello world with content types) is intended to be?
• put the "getting started" as the very first item in the reference section. It may be more intuitive to visualise how to set it up before understanding how it works (the architecture etc).

Consolidate the sections

Background

• Presently there are separate sections for reference, guides, cookbooks (and also samples)
• While it is clear from the perspective of the content creator how these sections differ, from the content consumer's perspective it leads to a lot of jumping around and context switching as the content for any topic is spread through various sections. For example, if I want to figure out how to handle response types (e.g. for a common use case of JSON APIs):
  • I might first look at the response bodies reference, but that doesn't tell me about content negotiation
  • The "Content negotiation" reference does not exist but that might be the next place I look
  • Scrolling down the reference list, I would see "JSON APIs" under "Common scenarios", which also doesn't exist. It's also unclear how this section differs from a Cookbook entry (e.g. there are unit testing entries both in common scenarios, and the cookbook)
  • I would then look at cookbook and see nothing there
  • The actual answer is to look at hello world with content types together with examining the source code to figure out what the various helper functions actually do.

Proposal

• I don't really have any firm proposals right now, so will highlight some alternatives

Alternatives

• Combine various sections of the reference into longer pieces. For example both hapi and express has a single reference for everything about the router, or writing middleware. pedestal docs has 10 currently active reference items for the same thing, most of which would be easier to understand if it was on the same page.
• Remove the cookbook to decrease the number of places users need to poke around.
  • errors handling/unit testing/custom verbs are already on the reference.
  • serving static files could go under "common scenarios" (e.g. hapi puts it under their main reference. express has a dedicated "getting started" guide that covers it. The latter approach could work if we move pedestal getting started to the reference (as discussed in the first section of this issue), and combine it with some common scenarios (again optimising for users to understand what to do before understanding how it works).

This is taking a while so will start with those 2.