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"
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