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.
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?
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.
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?
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
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.
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. No feelings being hurt.
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.
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:
Book
Ch2 (Getting Started) and Ch10 (FFI) rewrites merged.
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.
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.
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.
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
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).
No feelings being hurt.