Differentiate PureScript "Groups" in Documentation?

Chat
#1

https://en.wikipedia.org/wiki/Organizational_learning#Communities_of_learning

This is an interesting way to look at programming language communities.

Group (n):

  • what one member does affects and is affected by another group member;
  • members perceive themselves as a group and are perceived as a group;
  • and the group exists in a larger social system.

(A definition biased by academics funded by businesses, likely)

For PureScript, a group would be users of the language. I imagine there are multiple Groups in the PureScript “Organization”, such as:

  • “making SPA app, JS background”,
  • “making HTTP API app, Python background”, and
  • “making browser visualizations, math background”.

I imagine each of these groups has a particular scope of topics to teach and a preferred learning path. This is what made me think that considering the Groups in the PureScript community might be an essential part of organizing a documentation effort.

So, what do people here think about having a documentation effort which defines its various audiences based on “Groups” like this? Concretely, this would advocate increasing the quality of documentation for each of these Groups, but it would also reduce the amount of “generic” documentation which applies to everyone that is created.

(Originally posted on my Twitter: https://twitter.com/alex_berg/status/1116842897289240576)

#2

In the link you shared there were four “communities” of learning:

  • Individual learning (single developer)
  • Group learning (your description above)
  • Organization learning (PureScript maintainers / major stakeholders)
  • Inter-organizational learning (Programming language maintainers?)

In this structure, organizational learning would refer to efforts to teach users how to use PureScript effectively in general, whereas group learning would focus on some sub-application of PureScript like server-side / Node, client-side / SPA, etc. General documentation fits at the organization level; particular domains fit at the group level.

I do think it makes sense to write documentation, tutorials, etc. targeting a specific domain of PureScript, and I agree that it doesn’t fit as “PureScript” documentation so much as “How to use PureScript for X”.

I think people naturally contribute documentation, tutorials, etc. according to the domains they care about / work in. I’m a little wary of drawing formal lines or categories around these domains, though; it may be nice to have a directory of sorts to help you find more information by domain (client-side, server-side, math, etc.) but that’s about as far as I’d take it.

If someone cares enough about a particular domain, like Node, then it’s a fantastic idea to focus on documenting how to use PureScript for that domain and to put together an informal working group of others who also care about that domain. But I don’t think that should be a formal or PureScript-organized thing, just the advocacy effort of whomever wants to take it on.

If someone does organize a group to document a specific thing, then they certainly should post here on Discourse and reach out on Slack to see about finding others who care about that same thing who will help. I suspect the biggest challenge in all of this is to find others to fill out the group; perhaps the best way is to just start documenting & writing, share it regularly, and each time it is shared, ask for others to join the effort. Perhaps later other groups will form around other domains.

3 Likes
#3

That sounds like how I was thinking of it, too.

Believing this to be the best frame of mind, then, we are inclined to say that the documentation efforts of the PureScript organization should not be concerned with group-specific documentation. However, if one of these groups wants documentation, then someone from that group should start the effort. I talk about documentation here because I believe it’s a primary way of sharing group knowledge when the group is a geographically widely distributed one.

I imagine that person would find planning that group documentation project to be a large hurdle. Perhaps the PureScript organization should create a group-generic plan/template which that person can use to kick-start their efforts?

#4

I’m from the “SPA app, JS background” group. I would like to help with getting started documentation especially around build setup and tooling. When I was first evaluating PureScript I was initially turned off by large bundle sizes and slow build times. This is actually not the case with the correct setup but it took me a while to find the correct setup because the official docs don’t really cover tooling let allowing group specific tooling.

#5

Perhaps an approach like that of the Rust WASM working group could serve as a template, as I think it’s unlikely the core PureScript folks on the compiler would have time to dedicate to this effort:

#6

This sounds similar to what I started with commercial-purescript but later decided wasn’t the best way to accomplish my goals:

The PureScript community is much smaller than the Rust community, so I think there’s less need for so many repos and GH organizations. Perhaps make a single top-level organization named “purescript-groups” with a project for each group. This would be using the organization feature of GitHub for vanity purposes rather than permissions, which is fine. I imagine these projects will be primarily documentation, but if a project
for code is necessary, I think it should be created outside that organization, just to keep that organization simple.

So, if this sounds good, we can create “purescript-groups/web-spa” now.

What would we put in there, though? I suppose that’s up to the group admins, but it might be helpful to have a template from which to start. I think the best way to do that would be to have this first group figure out a structure that works for them, then later work to refine it into a template for other groups to use.

#7

Wow, I didn’t even realize the scope of the rust-wasm project. It’s significantly larger than I thought! It’s not as useful an example as it looked at first.

Yes, the PureScript community is much smaller than the Rust community. I’m on board with not creating a proliferation of repositories and organizations unnecessarily. We do have the perfectly fine purescript-contrib available to experiment with some of these ideas :slight_smile:

I am with you on being unclear on what exactly this group would be documenting and what content to place in this repository / organization to get things started. Though @kevinbarabash mentioned build times and bundling as a start, I’m hesitant to endorse creating new structure to maintain without a quite clear idea as to what exactly it’s supposed to create.

If the idea is that people do not have the resources necessary to succeed (without a ton of effort) in convincing their company to adopt PureScript for their single-page application, or in actually building that application, and that some tutorials and recommendations would help solve this problem, then it might be a better move to gather more information first. Specifically I’d want to be sure that the sort of problem that this effort is meant to address is a) solvable by documentation and b) understood well enough to be competently addressed.

It may be useful to reach out to folks who have succeeded or failed in developing a single-page application in PureScript or in introducing PureScript to their organization to learn more about what caused the success or failure. And to places like #purescript and #purescript-beginners for people who haven’t even attempted yet because some part of the process was a blocker. If it’s possible for a documentation project to emphasize the success factors and reduce or remove the failure / blocking factors, then I am 100% behind the effort and pledge to pitch in.

That’s why I ended up making purescript-halogen-realworld – one significant blocker I experienced when first using PureScript in a professional setting was that there simply weren’t approachable examples of how you even build a full SPA in the language, just small examples.

It may turn out that the big problems that prevent folks from succeeding with PureScript for building single-page applications require solutions other than documentation, like a splashy landing page with logos for their boss to look at or better purescript-the-language training or conveniences like create-react-app and so on.

Maybe time would be better spent adding in-depth tutorial content, advanced patterns, etc. to Halogen and React Basic and helping to create web sites like React’s to increase the legitimacy of our flagship UI libraries.

I’m certainly not trying to dissuade documentation / tutorial / teaching efforts, but we all have quite limited time to invest in helping PureScript succeed and I’d like to be sure that time invested will bear as much fruit as possible.

Recommended tooling for PureScript applications in 2019
#8

@chexxor I’m also thinking of a conversation we had a while ago in which you reminded me that writing is hard, documentation doesn’t build curiosity and excitement the way that projects do (especially for people doing this in their free time), and that most PureScript users are in a position in which this is a donation of their free time.

That’s why I wonder whether we’d see better results by encouraging projects that accomplish goals along the same lines as a documentation effort (for example, what about purescript-react-basic-realworld?) but in a way that’s more interesting to do on the weekend or contribute to in small chunks. Or, for example, there’s no bundling pipeline implemented for purescript-halogen-realworld following the best practices that @kevinbarabash has discovered; I just shove things into Parcel. That’s a good place to demonstrate this kind of thing because it has a built-in audience – there’s less of a discoverability issue.

There is quite a small PureScript community, so I’m looking for ways to lower the barrier to entry / make this sort of effort more interesting and/or rewarding to the sorts of people who might like to contribute and have to make a hard decision about how to spend their time. One thing that leads me to believe this could encourage more contribution is that I received several pull requests on realworld to either make improvements or complete some early pages once I’d begun the project.

#9

You mentioned the importance of appealing to companies to ease their minds when choosing to adopt PureScript. I agree with this, but I think it’s also important to define tractable goals for different parts of the community. I think that’s a good goal for the “organization” part, whereas this thread has been about the “group” part. The organization should be concerned with keeping the environment of the groups such that the groups can thrive, whereas the groups are only concerned with their own role/job function/interests. I just want to point out this distinction. I think it’s a useful one.

The RealWorldHalogen app is really interesting, though, because I hadn’t considered that as a component of a group documentation. I’ll spend more time thinking about that one, and perhaps @kevinbarabash can comment about how he thinks that would fit into that group’s documentation.

#10

@kevinbarabash I created that org I mentioned.

If you, or others, have comments on the Github org name or you’d like to make and manage a project in that org, send me a PM on Discourse here and I’ll add you to the org so you can make a project in there.

I initialized a place to manage a “template” that app groups can use when forming and managing their group: https://github.com/purescript-app-groups/ReadMe/blob/master/README.md