Ideas for improving PS documentation?

[chexxor]

Phil has said that he’d like the PureScript language to “stabilize” for the next year or so, and he’d like the documentation around the project to catch up. I feel like the documentation the PS community produces is slow and steady, which is great, but I feel like we can improve quite a bit!

I’m curious to find ways in which we can get PureScripters to contribute documentation towards various parts of the ecosystem.

Perhaps a more productive start to this conversation is: What barriers do people perceive to exist around contributing documentation?

[chexxor]

One barrier that comes to mind: Writing a from-empty, new doc page is hard! You have to think about questions like:

• Who’s the intended audience?
• What if the documentation/project maintainers don’t like the way I write? Catering to someone else’s seemingly meaningless writing style is not fun!
• Do I have to worry about a documentation style which is “maintainable” over time?
• Writing documentation isn’t rewarding. Also, I don’t need it because I already know how to use it.

I wonder what ways we can have to make writing from-scratch doc pages easier or less stressful.

I commonly hear that a programming language community should follow the model of the Rust community. Does anyone know what processes/culture they have around documentation? (I’ll take a look later)

[kritzcreek]

My main problem is that I’m terrible at writing

[thomashoneyman]

I’ll have more to say later, but first I want to drop this here. I think @joneshf originally clued me in to this:

https://www.divio.com/en/blog/documentation/

As an excerpt, this walks through several types of documentation, all of which are important:

• Tutorials
  Learning-oriented, allows a newcomer to get started, is a lesson (like teaching a small child how to cook)

• How-to guides
  Goal-oriented, shows how to solve a specific problem, is a series of steps (like a recipe in a cookbook)

• Explanation
  Understanding-oriented, explains, provides background and context (like an article on culinary social history)

• Reference
  Information-oriented, describes the machinery, is accurate and complete (like a reference encyclopaedia article)

For purescript-halogen-select this might break down like this:

1. Reference:
   Pursuit docs, brief notes on the purpose of non-obvious queries or helper functions. Might live somewhere like this: https://api.rocket.rs/rocket/

2. How-to:
   Walkthroughs of common things you need to do with the library, like embed parent queries, write render functions, use the component’s input type, and so on. Might live somewhere like this: https://rocket.rs/guide/

3. Tutorials:
   More in-depth walkthroughs of building components with the library, like How to make a date picker, How to make a typeahead. Might live somewhere like this: https://rocket.rs/guide/pastebin/

4. Explanations:
   Explanations of architecture and library decisions like Why we write components without render functions. Might live somewhere like this: https://rocket.rs/overview/

[marick]

Inspired by Matt Parsons (https://twitter.com/mattoflambda/status/997589748427341824) I’ll donate USD$15 to Doctors Without Borders https://www.doctorswithoutborders.org for each merged documentation PR. Tweet me @marick or mail me at marick@exampler.com upon merge.

At some point, I’ll stop donating, but certainly not before $300.

(Tip: now that documentation is ordered according to the list in module (....) where , there are some really easy wins just by moving most-often-used documentation to the top of the list, as in https://github.com/purescript/purescript-maps/pull/146/files)

[chexxor]

That’s a nice idea. Organizing docs by kind would be really helpful to new contributors, as each kind can have a certain structure, voice, audience, etc., and a template document can be used when creating new doc pages. It would also help in knowing what is missing, so instead of creating an issue to request “Document type class selection” it can be phrased “Explain type class selection”. Some kinds of documentation require deeper experience and understanding than others; I imagine the “Explanation” and “Reference” kinds would require cooperation with certain people whereas the “Tutorials” and “How-to guides” kinds seem like a relative newcomer to PureScript could contribute.

Currently, the purescript/documentation project’s “language” directory is mostly the “Reference” kind. The “guides” directory in the purescript/documentation project seems to be a mix of other kinds of docs, on the other hand, so that could use some organizing. As an example of another “Explanations” kind of docs, I’ve got a start for an explanation of bundling and I think a nice separate project would be an explanation of building/compiling.

We should just create a directory for each of these kinds of docs, include a template doc in each directory, and slowly move docs from the pre-existing directories into the new directories.

I’m mostly concerned with the purescript/documentation project. What other places need docs organization of efforts? Do we need a central listing of core & contrib libraries and their documentation status? If so, where would that go? I suppose we could make a new project, like “purescript/library-docs”, but that might fracture/confuse the docs-concerned community, so it might be better to just use a 1-2 doc pages in the purescript/documentation project.

[thomashoneyman]

We’ve just released a hopefully beginner-friendly tutorial on building a keyboard-navigable dropdown with Select here:
https://citizennet.github.io/purescript-halogen-select/tutorials/dropdown/

If anyone in the channel is curious to give the library a shot, I’d appreciate feedback on the tutorial! It assumes beginner-level familiarity with Halogen and no familiarity with Select. I’m also writing a much more advanced tutorial on building typeaheads with fancy features like async data fetching, but that will assume more experience.

This is a first cut to try and have better, more thorough documentation for PureScript libraries and I’d greatly benefit from feedback to make this better.

[btrepp]

I really appreciate the documentation for the select library. Particularly the intro with halogen.

The quick explanation of halogen helped me understand more about what queries are and how just to grok halogen.

I’m excited to learn purescript, but from a beginner perspective I find most of it assumes you know Haskell/know the concepts it’s talking about. I think it might be great if there was a focus on directing people at least to the beginners discourse. I’ve had good experiences with both it and slack, but when you are asking what feel like ‘dumb’ questions you end up wanting to google/find someone else who has asked the similar question.

[dariooddenino]

A thing I really liked about clojure was clojuredocs.org.

Along the documentation, users can provide usage examples, e.g.
http://clojuredocs.org/clojure.core/map

[JordanMartinez]

Hmm… I wish I would have known about the four types of documentation earlier…

There’s also my Purescript learning repo, which comes with the caveat that some of what it teaches might be incorrect since it reflects my current understanding of things. I think it contains a mixture of the 4 types of documentation above:

JordanMartinez/purescript-jordans-reference

[chexxor]

Even if it’s not a central doc project, doc projects like yours is great. I have one too, but it’s quite small. I think the small projects can be used as copy-pasta or as reference material when adding it to a central doc project.

[JordanMartinez]

Thanks!

Mind linking to your small doc project here? I can link to it in my repo. It may help by covering something I don’t already cover / covering some things better than I do. Or, it might just provide a different explanation that works well for other people.