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
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.
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
@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).
@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 
).
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.
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.
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.)
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
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
Yes. Or, since Discourse wants more than 20 characters: yes, da, si, sim.
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
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?
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.
“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.
I think we’re still a bit away from an official 1.0.
Well, it got merged now (hurray!).
I’ve been occupied with work and have been spending time on some other personal projects which need attention, but I’m still committed to this thread and the documentation effort.
Would it be worth spending time looking at other languages and how they organize their documentation efforts? I am interested in it, but I can’t judge how worthwhile that would be. I’ve heard that Rust is a model to look at, and I’ve been impressed with Idris and Agda’s documentation. The former has full-time maintainers and a much larger development community and user-base. The latter two have user-bases relatively similar in size to PureScript, so those would be nice places to reference.
I don’t know how to get an answer to this one, I only know what I would find helpful and what other people who comment here say would be helpful. Do you think it would be worthwhile to poll people or similar?
Judging from what I see in open source development, however, people like to contribute to something if it’s fun, has welcoming people already developing it, and the current state of development is such that it is easy to contribute to and easy to understand where needs improvement.
Thanks! I’ve been eagerly waiting for your response.
Would it be worth spending time looking at other languages and how they organize their documentation efforts? I am interested in it, but I can’t judge how worthwhile that would be.
I think it would be worth spending a small amount of time here, but not a great deal. I raised the question so that it would be considered, but I don’t know how helpful it would be. Each community is different, draws and repels specific kinds of people, and not every community’s goals/contexts are the same. What might “work” in one may not “work” in another. We’re also assuming that such communities would actually take the time to answer our questions and share any success/failure stories, tips/tricks that helped them, tool chains that worked/failed and why, etc.
I don’t know how to get an answer to this one, I only know what I would find helpful and what other people who comment here say would be helpful. Do you think it would be worthwhile to poll people or similar?
I think a poll/survey would help. If we market it well and get a few different types of people to fill it out, it would help provide some form of evidence to rally behind.
Also, I think this effort will need to move to a repo at some point. There are multiple concerns/issues here and discussing all of them in one thread is not helpful.
Where should we make a repo to host discussion on the multiple points of improving documentation?
Here’s a Github repo we can start with: https://github.com/chexxor/purescript-documentation-discussion/issues
Great. Let’s get started!