Documentation Work Queue

Moving from jBake to Antora has been an opportunity to go over each individual page of documentation, and each example.

Incorrect documentation is worse than no documentation.

Not everything can be done in a single pass, so this space is being used to track work that still needs to be done.

General

  • Make the reference docs more concise; hand holding is for the guides

  • Dial back the "if you don’t know Clojure" parts of some guides

  • Add an intro with all the key terms

  • Put the Guides and Reference into a reasonable order

  • Make better use of xref: linking between pages

  • Lots of broken links (currently in Howard’s IntelliJ bookmarks)

  • "Cognitect" → "NuBank NA"

Antora Technical Stuff

  • Create a custom UI theme

What is Pedestal?

  • Currently just a placeholder

  • Philosophy of Pedestal

  • Key terms and concepts quickly

  • Overview of the documentation

Server-Sent Events

  • Discuss options

  • Map vs. string events

service map

  • Break into service map vs. server map (on a new page) for things like :start-fn, etc.

response map

  • Are response headers converted to lower case?

  • :body may be extensible (e.g., chan)

WAR Deployment

  • Is web.xml this up to date w/ Jetty 11 (e.g., javax.*)

  • Update to discuss relevant Leiningen and Maven plugins

  • Need to eliminate Jetty/Servlet API dependencies from classpath

  • Discuss embedded as first option

Privacy Policy

  • Update "Cognitect" to "NuBank NA"

Defining Routes

  • Convert from terse syntax to table syntax

Contributing to Pedestal]

  • Pretty of date, should reference page on using snapshots, etc.

Terminology

  • Alphabetize the entries

Missing

  • "Pedestal with Component: Handlers and Dependencies" (never written)

  • Page about using snapshots (or Git coordinates)