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:
3 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

Discussion Topics:

  • Cookbook (repo)
    • Some libraries could use more runnable examples, but the library repo might not be the most appropriate place for these. A cookbook repo seems like a better home.
    • Discussed hosting cookbook examples on TryPureScript, but this won’t work for node.js, routing, and multiple-file examples.
  • mdbook for guides
    • Using anchors and CI ensures all code snippets are valid.
    • Similar to literate-purescript, but more flexibility in choosing snippets.
  • Type errors
    • More instruction or examples of troubleshooting type errors could be helpful.
    • The errors section of the docs repo seems like a good place to contribute these examples.
  • Language benefits could be documented more clearly for folks who are considering whether to dive in. Especially when compared to TypeScript, which offers many of the type safety wins with minimal learning curve (assuming background in JS).

Updates since last meeting:

Next Steps:

  • Showcase mdbook best practices in PS Book
    • CI tested anchored snippets
    • Collapsible imports in snippets
  • Contribute cookbook examples
2 Likes

Updates since last meeting:

  • Cookbook
    • Developed a nice CI process
    • Added a few recipes
  • Book
    • Chapter examples and exercise solutions are now tested as part of CI.

Next Steps:

  • mdbook showcase (carry-over from last week’s goals)
  • Continue contributing cookbook examples
3 Likes

Updates since last meeting:

  • Cookbook
    • Number of recipes increased from 5 to 31
    • Usability and CI improvements

Next Steps:

  • TBD from today’s meeting. Will edit afterwards.
4 Likes

I have no problem putting in small PRs to change bower commands to spago when I come across them. Would this be welcome or are we holding out for a more automated solution? As someone new to to community my immediate reaction was that these packages were unmaintained. Then I realized this is just very common and now it’s just an eyesore.

1 Like

I’m converting all of the PureScript Contributor libraries to use Spago for local development and in the installation instructions. I think most library authors would be amenable to adding the installation instruction.

1 Like

Right now, our package registry is in a transitional state, and it will probably remain this way for a while. Until the new registry is properly up and running, libraries need to include a bower.json file with correct dependencies, otherwise they will have incorrect information displayed on Pursuit (or if the bower.json file is missing, you won’t be able to publish to Pursuit at all). For this reason I think the best approach is to stick with bower for now when developing a library. If you’re not a library author, you shouldn’t need to know or care about bower, and so I’m happy to take PRs that change installation instructions or other documentation which mentions bower, but aside from that I don’t want to change the core libraries or any of the libraries under my personal github account in that way just yet.

1 Like

Really? Pursuit is dependent on a bower.json file in the package repo? I would think it would it be relatively trivial to add support for spago’s files :thinking:

1 Like

It’s not trivial for two reasons: firstly, some people are still using bower, and not having a bower.json file means that your package is actually unusable for those people. Right now I think it’s good etiquette not to split the ecosystem so that packages can be consumed by anyone. Secondly, libraries really ought to be published with version bounds on their dependencies so that people can get an idea of what versions of things it’s supposed to work with; just knowing that a library works with a single package set isn’t particularly useful if you want to use specific versions of other libraries which aren’t in that package set. Finally, this would require building knowledge of the the spago file format into the compiler, and that isn’t something I think would be such a good idea at this stage, especially with the registry work ongoing (which would change all this again).

2 Likes