PureScript documentation efforts in 2019

#1

Looking back on 2018, I would guess there wasn’t as much progress on developing documentation guides which newcomers to the language would find really valuable, at least not in the purescript/documentation repo. Actually, that repo’s scope seems to be reference documentation of the language itself and just a few core tools, so newcomer-targeting documentation would need to be somewhere else.

Jordan’s guide is looking like a pretty good project to contribute to: https://github.com/JordanMartinez/purescript-jordans-reference - perhaps those interested in documentation add that one to their radar.

More importantly, is anyone here interested in putting together a “task force” for newcomer documentation? I think what we need is 2 or more people to commit to improving the documentation situation for a certain audience, call that group a “task force”, then have them meet once every 1 or 2 weeks to check the status of the situation and keep motivated on improving it.

For what other area of documentation would you like join/create a task force?

4 Likes
#2

I also have a lot of crap written here: https://purescript-resources.readthedocs.io/en/latest/

While I don’t really expect people to want to contribute to that, people should feel free to pull information from it to form other docs.

4 Likes
#3

A big reason I like Jordan’s project is he has written up a bunch of issues which highlight new things to add to the documentation, which should make it relatively easy for people to help out that project.

edit: Also, re-reading my original post, I sounded more pessimistic than the situation deserves. I certainly notice and appreciate the docs you have written and others have written for their personally-contributed libraries. I believe my pessimism in the OP was due to disappointment in myself for not being able to make lots of great docs. Perhaps also it was motivated by my wanting to see, but not seeing, a concerted/organized effort for docs improvement. Even now, I’m not sure an organized effort is better than individuals writing docs on their own – I think both types of docs are needed.

1 Like
#4

@chexxor Most of my links that I open issues for come from these sources:

  • the Purescript Slack channel where smarter people than me (i.e. Justin, Gary, MonoidMusician, etc.) link to something or explain something that will not be archived, so I do it
  • Hacker News Best
  • Haskell Weekly

Also, Justin and I’s goals are different. Mine focuses purely on learning with the by-product that I happen to document things for others while Justin’s actually documenting it for others. I also think they cover different things in better/worse ways than the other. For example, Justin definitely has more ecosystem-y things than mine.

@justinw I just realized that I’m not watching your GH repo for that site. So, if you ever add any changes, I’m not aware of it, so that I can link to that section. Whoops!

To both of you, I think the question in my head is: “What is currently lacking in the ecosystem of documentation for Purescript?” When one adds up my repo + Justin’s blog posts + Justin’s RTD works + Pursuit docs + , what are we still missing?

2 Likes
#5

First of all, thank you all for your time and energy! I’ll try to share some constructive criticism from someone who has had a fair amount of exposure to the community, but is still very fresh to working with the language itself.

To answer your question @JordanMartinez, from my perspective the missing pieces are structure, ease of discoverability, and overall sense of home base for the language.

As a user landing on purescript.org, the learning process:

  • can feel fragmented and makes finding resources harder than necessary. It can also set up a high barrier to entry, as some resources require commitment to the language (forum/slack/github) to discover
  • leads to pitfalls and unpleasant first impressions (such as current top recommendation being for Phil’s now outdated Purescript By Example book)

My vote would be to try and make the official website the first destination for finding answers.
This can strengthen the brand identity of the language and garner trust with users.
I’d like to see the website expanded to include:

  • updated and structured approach for learning the language (reference Rust)
  • current (and expanded) content of the documentation repo (reference Reason)
  • search
  • links to the vast treasure trove of community community resources (with appropriate disclaimers & dates)
  • official announcements

I realize that this is all easier said than done (especially generating the content), as well as unfair to compare to larger and older languages.
For what it’s worth though I can try and help as much as I can with the design and front-end work if needed.

Some more relevant reference would include:

3 Likes
#6

I would really like to have others contribute to the website repoistory if they feel like they could effect some meaningful changes here: https://github.com/purescript/purescript.github.io

#7

I feel like the PureScript.org website is Phil’s, and there isn’t any mention in the readme that contributions in general are welcome, nor do I see the scope or purpose of the website describes in that project, though I could be missing it. It’s hard to know how to improve the website when there’s no roadmap or goal or boundaries or defined audience.

#8

I’m not planning to finish An Outsider’s Guide to Statically Typed Functional Programming because my original plan for the book doesn’t fit the world-as-it-is and I’m trying to avoid the sunk cost fallacy. I’ve made the starting price $0 while I figure out what to do with it.

Most of the book is Elm, but I have a few chapters starting the transition from Elm to PureScript, as well as a couple of partially-finished chapters.

I wouldn’t be optimistic that the PureScript content can be extracted into something that works standalone, but I could be wrong. If someone sees a way to make use of the text, let me know.

.

2 Likes
#9

@justinw @chexxor When I did open up a link to add my learning repo to the website (which I felt would help), I was redirected to do it in the Documentation repo:

@ketch I experienced something similar, which is why I started my learning repo. I did have one advantage: I had already read through “Haskell: Programming from First Principles,” so some of the FP content was already somewhat familiar.
I think that many people want this (there’s been other related threads on this forum), but the biggest issue is time. Most who know enough to write such content are busy working on other things (e.g. job, compiler work, etc.). Also, Phil himself stopped updating the Book because it really is a huge time investment that is quickly outdated by a new compiler release. Having an epoch-based documentation like Rust would make more sense.

@marick This thread might not be the best place for that discussion, but I’d be curious to hear your thoughts why FP languages aren’t ready for mainstream yet. (I can see reasons why that makes sense).

#10

@JordanMartinez - I think @marick is offering use of the content he wrote for his book for people to use in later PureScript documentation projects, with is permission. If that’s the case, I think it would be a great help!

If what @ketch says is representative of a considerable percent of the people wanting documentation, then structure, discoverability, and a sense of home base is what’s needed.

I think an interesting thing is that the first answer for “a sense of a home base” of documentation isn’t the GH/purescript/documentation project. I wonder why that is… Perhaps because there’s a perception that a GitHub repo’s target audience is participants in the project, whereas a custom domain-named HTML website, like purescript.com, has a target audience of the general population/consumers/users of the language?

What follows in this post is a proposition for a path towards a better documentation state, because I’d like to start seeing action items at some point in this thread, but I still want to hear other propositions or points we’ve missed discussing.

It seems like structure is the main thing that’s needed, then. Discoverability can be had by linking to it from the purescript.org page, and the sense of home page can be had by having a “proper” documentation website like the languages have in the other links that @ketch included. I feel like the GH/purescript/documentation project will be hard to persuade to be the all-audience documentation hub that this thread has been leading towards, which means a new project will need to be started. If doing that, it should be started as a virtual clone of the project structure and build process used by the doc project we want to aspire to be. After that, we can work to move content into that project from other sources.

If we want to try setting up a “proper” doc web site, out next step, then, is to collect a few existing doc projects from which we can choose one to “move in to”, then do some analysis & comparison to choose an appropriate one. Part of this step, perhaps, is to define the structure/organization of the doc site, as @ketch expressed this to be rather important part of a doc site (and I agree, as I like organization :slight_smile:).

The next step, then, is to begin moving content into it, and making work items for missing content. These work items can be worked through by a volunteer working group. An essential part of such a working group is to commit to meet regularly to ensure progress is always being made. I think a key part of the success of this working group would be to keep the team’s responsibilities/work load realistic. Writing whole new doc pages is a ton of work, so we’d need to either find a way to make doing that easier or we’d need to find an alternative, such as assimilating a doc page from existing material, like personal docs, other prog lang’s docs, etc.

#11

@chexxor

the first answer for “a sense of a home base” of documentation isn’t the GH/purescript/documentation project. I wonder why that is

Here’s my thoughts on this matter:

  • The PureScript website describes the documentation repo as a place “where you can find articles, tutorials, and more.” Most notably, it seems like a general “Here’s some ideas that are useful, but they are not start-to-finish explanations that make you productive in this language, especially if you’re a beginner.” Rather, that it achieved via the book, which is described as “The free PureScript By Example book contains several practical projects for PureScript beginners.” This description seems to indicate that one should start here rather than elsewhere. It’s got the official website linking to it rather than something else. It’s got the “By Example” title. It includes comments about ‘projects for beginners.’ And it’s free, so the initial investment is curiosity and time, not money.
  • It’s only when one starts to encounter problems with the Book due to its outdated nature (and starts to experience “friction” in the learning experience) do they then look at the documentation repo, which further frustrates them because it is not a replacement for the Book. Likewise, my learning repo (which the documentation repo now links to thanks to @chexxor’s follow up) is not a replacement for that book but does serve to supplement some of its ideas/explanations.
  • I think the best short-term way we could help the learning experience is by taking down the link to the book on the website (stops that initial frustrating learning experience), update the site to emphasize the documentation repo as “the” place to go for learning resources, and add more context to the book’s link (i.e. the book’s code is outdated, but the principles are still valid. See dwhitney’s fork of the book’s code. See Jordan’s learning repo for supplemental reading.). Unfortunately, I’m not sure whether linking to dwhitney’s fork will be done by that “official” repo because of copyright reasons.

I feel like the GH/purescript/documentation project will be hard to persuade to be the all-audience documentation hub that this thread has been leading towards, which means a new project will need to be started

That seems likely.

If doing that, it should be started as a virtual clone of the project structure and build process used by the doc project we want to aspire to be. After that, we can work to move content into that project from other sources.
… out next step, then, is to collect a few existing doc projects from which we can choose one to “move in to”, then do some analysis & comparison to choose an appropriate one.

That makes logical sense, but I wonder about copyright issues. For example, could we start with the current documentation repo, especially since it’s license isn’t immediately obvious?

An essential part of such a working group is to commit to meet regularly to ensure progress is always being made.

I actually disagree with the “meet regularly” idea. Rather, I agree with the “next actions have been clearly defined and self-assigned to individuals with clear deadlines as to when they’ll get it done.” As I see others contribute and hit those deadlines, I’ll want to contribute too since “the cool kids are doing it and I want to be like them.”

When you propose your ‘new project’ idea, do you intend to get “official support?” Unless we get that, a number of things become more difficult

  • keeping the documentation up-to-date, especially when a new version of the language is released
  • having increased visibility by having a link on the language’s website to that project
  • not creating friction in the language’s community as a whole because of disagreements about how things should be done

Lastly, I’m curious about how you would motivate people into actually contributing towards this effort. I see that there are a number of efforts by various people, but I’m not sure what their incentives are and how much this project would align such incentives.

For example, the motivation behind my learning repo was learning PureScript and the FP paradigm as a whole. My repo gives me full control over what gets included/excluded, how it’s structured and worded. There’s a lot of benefits that provides without any external influence. The only downside I can see is that I don’t have smarter people (e.g. core contributors, other well-informed people) correcting me all the time. So, I might think I understand a concept only to realize months later that I was incorrect the entire time (happened quite recently actually).
I’m also more likely to contribute if you describe this project using the Getting Things Done methodology/framework.

Likewise, @justinw contributes documentation, but I’m quite confident his incentives are much different than mine. He uses Read the Docs and his blog to document things. Those might be better formats for his intended audience, which is likely different from mine.

#12

The key questions I think would be effective to discuss next:

  • What is the easiest way to run an effective doc project staffed by a relatively few number of volunteers?
  • What motivates people to contribute to a shared doc project?

Following is long-form thoughts which lead to the above questions.

I had the “meet regularly” idea because I guessed it might help me, personally, by keeping the documentation project on my mind to keep this long-term project a priority, but I’m not sure why I think it would be helpful. Perhaps because it would feel more social, or it would feel like there’s a committed team I am helping? Anyways, this topic can be resolved by supporting interested contributors motivation models, and there is likely to be more than one.

I proposed the “new project” idea because it seemed like that might be the right end-product our doc project needs at that point in this discussion. But, I really don’t know what the right end-product is for us. Most likely, it’s whatever our small community can produce, continue to prioritize, and continue to maintain over a long time. This situation, then, changes the question from “what should the end-product be?” to “what is the most maintainable and motivating way we can produce a great docs hub (without consideration of a specific end-product)?”

About “official support” - I think “official support” is whatever doc project has the most traction, progress, and maintainers. Once that is had, I think links to that project will be easy to get. Until now, it seems to me like the most successful way our community has for producing docs is for individuals to write them on their own in their own blogs or where-ever, likely because it frees them from needing to persuade others on content/quality/style/etc… This leads me to think that perhaps a successful team-based central doc project would be simply a curation process, in which net-new content and non-trivial changes is assimilated from individual’s doc projects, with the author’s permission, of course. We’ve had the GH/purescript/documentation project for awhile now, but this central, team-based project just doesn’t seem to get much net-new contributions. So, what about its management style needs to change?

@JordanMartinez, your ideas for concrete, short-term changes we can do now to improve the situation are good - you or someone should remember to send some PRs. Also, the split between the GH/purescript/documentation project and the “PS by Example” book is a good point - I wouldn’t have considered that it might confuse learners or new-comers. Personally, I have never considered the “PS by Example” book a source of documentation at all, maybe because it feels like it’s teaching from one-person’s point-of-view of how the PureScript language can be used, rather than explanations of the language design itself.

A closing thought I just had - I wonder how wikipedia manages its content pages. (Or maybe we shouldn’t use them for reference, as they won’t even accept a PureScript language page, haha.)

#13

I opened an issue for that here:
Remove link to Purescript by Example & emphasize Documentation repo

I’d rather not submit a PR until this has been discussed further.

1 Like
#14

I’m going to address your questions first:

  • What is the easiest way to run an effective doc project staffed by a relatively few number of volunteers?
  • What motivates people to contribute to a shared doc project?

This is my understanding of the GTD methodology/framework:

  • [Presuppositions] We presuppose that
  • [Authorities] certain “authorities” (i.e. sources of data) are true and accurate, which
  • [Interpretation] we interpret in various ways and use to
  • [Context/Narrative] describe the current context/narrative, which
  • [Purpose] a) calls for some purpose to be fulfilled
  • [Principles] b) whose fulfillment must abide by certain principles / core values,
  • [Outcome] c) where “success” for this part of the context/narrative is a clearly defined ‘X’.
  • [Brainstorm] We brainstorm various ways to achieve X and decide to take some Path/Plan to get there which abides the most with our principles and strategically uses our limited resources,
  • [Next Actions] delegating specific actions that can be done “now” and which do not require anything else to be done before they can be done (e.g. waiting for someone to resond).
  • [Current Actions] When we have time and the mental energy to do so, we do our next action and slowly make progress.

The framework works from the top-down, not the bottom-up. When you opened this issue, we were starting at the brainstorm phase. In the above questions, we’ve transitioned to being at the outcome / context phase.

So, here’s what I’d like clarified:

  • What is the current context/narrative?
    • Why have current documentation efforts “failed?” Let’s learn from the past. If possible, let’s also improve what we already have rather than starting an entire new project.
    • How have other languages dealt with this issue? What worked well and what did not? Did they have a large or small number of volunteers?
    • Who would be willing to contribute and under what conditions? How qualified/knowledgeable are they and how should that influence what contributions they can make? Do people really want documentation enough that people will contribute if there are people coordinating the efforts? What would be the threshold we’d need to pass before doing this?
    • (restating another idea you mentioned in an earlier comment) What documentation already exists elsewhere, in which case we just need to port the code to PureScript for easier understanding?
    • (restating your question) What is the easiest way to run an effective doc project staffed by a relatively few number of volunteers? What tools/workflows are available that make this project easier?

Once the above questions are answered, we’ll have a better understanding of these questions:

  • Purpose
    • Why are we doing this? Why should others join? What will be a strong enough purpose to get people to continue contributing when they have other competing priorities?
  • Principles
    • What principles will we abide by when designing and doing this? These will help answer questions like “We can do X or Y. Which one should we choose?”
  • Outcome
    • What does ‘success’ actually look like? (restating your above question)

I’d like to comment on the other parts of your comments, but I’m out of time for now.

1 Like
#15

Yes. Or, since Discourse wants more than 20 characters: yes, da, si, sim.

#16

In addition to long-form documentation, there’s a desperate need for API documentation, which means pull requests to various repos. I was doing that for profunctor-lenses (e.g.), but my motivation for future work is low.

Perceived importance goes hand-in-hand with quantity. (“When there’s a hot story, the media usually likes to pile on with background pieces, context pieces, related pieces. This is flood-the-zone type coverage as former NYT editor Howell Raines dubbed it.”) (“Flood the zone” gets its origin from American football. Sorry for the parochialism.) So maybe a whole bunch of pull requests might raise the perceived importance of documentation.

(Confession: this is really a backhanded way of getting someone to maybe merge my almost-six-month-old doc pull request for Data.Tuple.)

1 Like
#17

In addition to long-form documentation, there’s a desperate need for API documentation, which means pull requests to various repos.

That’s a good point.

Also, what’s the license for using your book in this documentation project?

#18

If the language and tools are stable enough now, perhaps it’s time for the 1.0 release. It would allow the documentation (including the book and main website) to catch up.

#19

“what’s the license for using your book in this documentation project?”

Depends on the use. For a substantial use, a “used by permission of Brian Marick” and a link to the source. (That implies asking for permission per-use, which I doubt would be a problem.)

I’m not ready to waive copyright.

#20

I think we’re still a bit away from an official 1.0.