Documentation Improvement Efforts

[milesfrain]

Discussion topics:

• Pain point - Difficult to find instances and examples for classes. Should hopefully be improved with:
  • Searchable instances in pursuit (proposed).
  • Doctest examples accompanying all instances.
• Pain point - Lacking documentation on direct and lightweight DOM manipulation without using a framework.
  • Use of web-dom requires good knowledge of PS and W3C spec.
• Proposal - Edit all libraries to ensure they:
  • Don’t have bower install instructions. Debatable whether spago instructions should be listed, or if this could be automatically added by pursuit.
  • Use spago instead of bower. This should make library contributions and CI easier.
  • Have doctest examples for every function.
  • Have CI enabled in repo.
• Proposal - Have the registry CI enforce some of the above requirements.
• Proposal - Enable linking or embeding Try PureScript for:
  • Doctest examples in pursuit
  • Book examples (proposed)
• Proposal - rewrite Ch12

Updates since last meeting:

Book:

• New tests and exercises added to Ch7 “Applicative Validation” - Thanks @oldfartdeveloper
• Ch2 “Getting Started” rewritten. PR awaiting merge approval
• Ch10 “FFI” rewritten. PR awaiting merge approval

PRs for improving library examples and docs:

• PRs approved, awaiting merge:
  • Examples for NonEmpty
  • Examples for alt, <|>
  • Examples for sequence and traverse
  • Convert bower to spago installation instructions in arrays
  • Improved explanation of orphan instances
  • Corrections for Lazy List
  • Example for const
  • Examples for lift2
  • Aff disclaimer
• PRs awaiting review / approval:
  • Examples for parallel - needs decision on conversion to spago for CI
  • Running time notes for Arrays
  • Guard limitations in let
  • Halogen docs for IDE tooltips
• PRs merged:
  • Argonaut recursive generic example

Next steps:

• Work on Ch12
• Continue improving library docs and examples
• Setup CI for some libraries (parallel)