Documentation Improvement Efforts

This is a wiki post to track active documentation tasks and ideas to consider. Posting a log of meeting minutes in the thread below. Feel free to discuss any of the items, and I’ll pull any new ideas up to this top post.

Active Tasks:

  • doctest / purepur
  • book
  • Move some library-specific documentation and examples from Jordan’s Reference into their respective libraries

Ideas / Todos:

  • Improve library documentation
  • Replace bower installation instructions with spago, eg. arrays.
  • Add doctest examples
  • Add additional standalone examples
  • Cookbook and tutorials for web frameworks, for example:
2 Likes

Notes from Today’s meeting

Discussion topics:

Pros and cons of adding examples and guides to libraries:

  • Con: Burdens the maintainer with more content to update when making library changes.
  • Pro: Helps ensure that guides and examples stay up-to-date.

How best to organize existing documentation.

  • Three major sources:
    • Docs repo
    • Book
    • Jordan’s reference
      • May be good to split this into a reference and separate guides
  • Look to how other languages manage documentation, eg. rust:
    • There’s a book
    • And a reference
      • Both the docs repo and Jordan’s Reference cover similar reference material.

Tutorials for frameworks (Halogen and React)

  • Existing tutorials and example apps:
    • Realworld - halogen - currently being updated for Hooks
    • Todo MVC - react-basic - more of an example
    • Address Book - react-basic-hooks - more of a walkthrough
  • A more introductory example (like the JS react tutorial) might be nice too.

Other topics noted in first post.

Attendees:

  • miles
  • Jordan
  • csicar
  • Jamie
  • Giulio
  • Delhia
  • paulh
  • Daniel
2 Likes

Thanks @milesfrain! I’ve opened https://github.com/JordanMartinez/purescript-jordans-reference/issues/472 to track the migration of some of my content into their specific repos.

2 Likes

I’ve opened a PR for that here: github.com/purescript/purescript-arrays/pull/171

Could we automate some of the bower to spago changes (or at least automate detection)? Maybe clone all the repos in the latest package set and do a find in all the readme.md files?

Edit: Or if this is something common to all packages, should installation instructions just be built into pursuit?

Maybe a github search? Not perfect, but might help https://github.com/search?q=bower+install+pursuit+filename%3AREADME.md&type=Code

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:

Next steps:

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

@paluh suggested another idea in the backend room. Could we standardize a tool for doing “literate purescript” and incorporate that into PS libraries?

Also, it seems like a number of people agree that there should be a “purescript cookbook”. We have a “book” and a “reference” but not yet a “cookbook” part of documentation.

6 Likes

Is that a proposal to use literate-purescript to invert code and comments? Is this to make it easier to work with files that are mostly comments? Could we also make things easier by just using block comments ({- -}) instead of per-line comments (-- |) for docs in libraries?

1 Like

No, just a suggestion. When it comes to documentation, I think we have the following methods we could use:

  • inline documentation (e.g. what appears when you hover over a function / value name)
  • doc tests (e.g. code that is written in inline documentation that can be run)
  • literate purescript (e.g. a combination of a Markdown file whose extract code can be run as an example)
  • examples folder (e.g. code that appears in the same repo as a project but outside of its src or test folder; usually comments explain what’s going on)
  • “errors” folder (e.g. take a simple example that compiles, duplicate it, make one thing incorrect, and show which compiler error arises)
  • blog posts, tutorials, videos, etc.
  • cookbook

Each have their tradeoffs

  • inline documentation is easy to write, but isn’t necessarily helpful because no examples are shown. Sometimes examples speak louder than written explanations. However, they will show up on Pursuit.
  • doc tests are good for small snippets of code, but is not ideal as a stand-alone example. Similar to inline documentation they will show up on Pursuit.
  • examples are good for stand-alone examples, but it can be harder to find them if one doesn’t know where to look. One has to look at the repo to discover them, which isn’t apparent on Pursuit
  • literate purescript can be a more readable version of the examples idea.
  • errors folder is not as common, so people might be less familiar with them
  • blog posts / tutorials / videos are hard to find but can often provide more context than just examples alone. However, they can become out-of-date quickly due to not having CI notify authors when they no longer compile
  • cookbook can provide a large number of “best practices” or answers to “how do I do X?” To prevent dependencies between “recipes,” it would require a lot of duplication among the folders (e.g. each example is a spago project).

@paluh mentioned this to me in a separate conversation, but it might be a good idea to clarify what are “best practices” for documenting a project. I think the following would help

  • public entities (e.g. types, functions, type classes, values, etc.) have documentation
  • ReadMe includes link to its Pursuit docs
  • ReadMe covers the “why” behind the library, a comparsion to other related libraries, and a quick start for using it (note: this might be literate purescript…?)
  • an examples folder shows how to use it
  • if the library uses complicated types, an errors folder shows how to fix common compiler errors
1 Like

Thank you for writing this Jordan, I agree that there should be one standard way to document, which we can point to as good default.

I think whatever solution we come up with, it has to be discoverable from pursuit documentation page and source page.

Let’s take Aff Bus as an example. Currently it support only Text based documentation. So if we modify source code to point to example or test it could look like this in pursuit and source code.

Pursuit:


or

Source:

If we let it be in the project, it can be checked and maintain with version. Easy to discover from documentation page and even from the code. Basically you would not have to go for a hunt elsewhere.

My point is if there is great documentation with examples explanation somewhere else, and you cannot find it, then it doesn’t matter. Like it doesn’t exist.

Notes:
I just made example of the links, the looks can be changed if needed. Comments example type and comment test type would need to be added to compiler, and symbols chosen to be anything.

These are just my suggestions, if you don’t like them, ignore them. :slight_smile: No feelings being hurt.

3 Likes