Red Flag: Should we improve PS Documentation _now_?

[JordanMartinez]

Context

So, I spent the past week (or two?) reading through a lot of different sources. Many of these sources were created/written/said sometime in the year 2018. So, some of what they say might be outdated and we have not yet gotten formation from some sources of data (i.e. #31).

That being said, when we first started this effort, we presupposed something that I'd like to bring front and forward:

We need to improve PS documentation/onboarding process now, not later

Due to what I know/infer now, I'd like to challenge this presupposition by asking 'why?'

Reasons

There's a few things that come to mind:

• Garyb stated a few things over a number of sources
  • they are currently prioritizing the language's development over things like documentation
  • people misunderstand a v1.0 language to be the same as a v1.0 ecosystem, which it is not. This is why he is hesitant about releasing a v1.0 language.
• Phil Freeman stated that he did not want to update the Book because
  • the cost of time/energy to update it is quickly undone by breaking changes (which is quickly demoralizing)
  • there is no specification towards which the language is being developed, making it hard to know when he should 'start' updating it in time for a v1.0
• The PRs that do get reviewed for various documentation efforts don't necessarily get merged in a timely manner
• There is generally no incentive for someone who knows enough to write good documentation to actually write good documentation.
• Often times, there are many "good things" people can do. However, the thing which distinguishes "successful" people/businesses/efforts is working on the "overall best" things rather than the "enjoyable" things. In other words, one must always consider the opportunity cost

In other words, there is no mutual understanding as to what a v1.0 will be, such that we know, "If we start at time X, working on documentation while contributors work on the language in parallel, then the v1.0 of the language and our v1.0 of some documentation/onboarding process will be complete around the same time."

Moreover, if we do submit documentation PRs, we might actually act as a bottleneck to the PS language contributors: rather than developing the language and moving it closer to a v1.0, we're stealing their precious time away by making them review documentation PRs. By having less time to work on the language, it actually does more to delay a v1.0 where such documentation would not become outdated as quickly.

Furthermore, we currently have a number of people who want to see this language succeed. Alex, myself, and a few others would like the documentation situation to improve. Others have offered to take over the maintainership of some PS infrastructure. While we may have the manpower to do work for the benefit of the community, is this documentation work the kind of work that we can do now that will benefit the community the most in the long-term? Considering other things we could do (develop libraries that solve problems), would doing this other work be more beneficial long-term than doing the documentation work?

Lastly, I need to take a step back and consider my own personal incentive for this. I want but do not yet have a full-time programming job. Since I do not have a CS degree, the only 'proof' I can provide that I know how to write good code is by building a portfolio of various projects. Given the amount of time/effort that this documentation effort will take, I question whether I would stick with it for that long.

Remaining Questions

So, what I would like to ask is, "Should we still continue this effort at this time? Will the resources we invest into this effort (e.g. time, mental energy, collaboration with others, etc.) be worth its return (better documentation, onboarding process, etc.) given that we are in this current context?"

Another way to phrase the above question is, "How can we continue this work while accounting for the above issues?"

Or if we find that we cannot account for the above issues at this time and that we should not continue the effort now, "How can we 'save' the work we have already done to make re-starting this effort in the future "easier?"

[chexxor]

An excellent point of view and a good time to bring it up. I feel like this thread will inform the goals of this project in a healthy way.

people misunderstand a v1.0 language to be the same as a v1.0 ecosystem, which it is not. This is why he is hesitant about releasing a v1.0 language.

This is a great point. PureScript seems to be in an interesting situation where one portion of the language users want a 1.0 release, for language stability, while another portion does not want a 1.0 release because it can be interpreted as a signal that the language is "ready" for people to come adopt. If the language is not ready to adopt when a 1.0 release occurs, but rather is merely a signal that the language itself is stable, the problems caused by this miscommunication can be mitigated by improved communication where newcomers would come to learn and adopt the language. "Welcome to PureScript 1.0. This release marks the start of a long timespan of stability in backwards-compatibility in the language itself. However, this does not imply the language is ready for mainstream adoption, as the language is missing some conveniences such as documentation, an ecosystem which is catching up, compiler front-ends/build systems, etc.(I don't know what else)."

On the other hand, is it possible that the language will asymptotically reach 1.0 because of the slow documentation effort? That is, could pushing hard on the documentation side encourage and inform what a 1.0 release looks like? For example, perhaps the documentation project will help define what features a 1.0 version of PureScript should have. And, could having a smooth and friendly 1.0 event, perhaps flourished with educational and introductory text by the docs team, grow the new users in a healthy way? Could this healthy influx of new users translate into a growth in long-term users, which translates into new contributors to the compiler, documentation, and libraries?

Given the amount of time/effort that this documentation effort will take, I question whether I would stick with it for that long.

I imagine this documentation project will be a forever project, so it's pretty likely that few people will contribute through its entire duration. Perhaps an important goal for this project, then, is to construct a framework and culture for the language that enables the documentation project to effortlessly or enjoyably grow. I'd like to see it enter a state that would enable you and I to drop out of the project for a few months or years and come back to see it has "naturally" grown and towards a good product. This is one of the reasons that I'd like to take time to reach out to other language maintainerships to learn how they manage their documentation project -- to discover what state we need to reach to enable the initial hard push on the documentation project to relax a bit.

the thing which distinguishes "successful" people/businesses/efforts is working on the "overall best" things rather than the "enjoyable" things.

This is something I haven't thought of. It's interesting! I've always thought of the PureScript project and its development to a hobby project to most of its contributors. If it's a hobby project, then its main reason people are here is because it's enjoyable. Does this preclude it from being a "successful" project? Perhaps we can gather what most contributors think a PureScript "success" looks like? Due to varying opinions and goals, I imagine the answers would categorize the contributors into a few groups. Amongst these groups, what would the common aspects of this "success" look like? What are the most important 1 or 2 invariants/principles of each group? This would inform where PureScript can go, which would allow us to derive opportunity cost on our decisions here.

As an aside, I just started listening to the "Software as a Reflection of Values With Bryan Cantrill" episode which might be relevant here. As a data point, in the past I've brought up this idea to some people in the PureScript community and the response was more "I don't see how values are relevant" than "ah yes, documenting this project's values would help us so much!". I feel like having the PureScript project thinking about a shared vision of "success" is akin to thinking about a shared set of values. So, if we do go down this route of having people define a shared set of values, it might be fruitless. It's possible that changing the wording or the context would produce different results, however.

"How can we continue this work while accounting for the above issues?"

Perhaps this question can be better answered after we finish the Sources phase of this project. Or perhaps just before we actually start down the route of taking the steps of realizing the goals we select. I think "saving" our work here would simply be setting up the structure for realizing the goals of this project, purescript-documentation-discussion, though I might need to think a bit harder before settling on this answer.

[JordanMartinez]

If the language is not ready to adopt when a 1.0 release occurs, but rather is merely a signal that the language itself is stable, the problems caused by this miscommunication can be mitigated by improved communication where newcomers would come to learn and adopt the language.

That idea works in theory, but I can still see a mass of people complaining that PS doesn't work properly despite knowing about that. So, it can help, but it's no guarantee.

On the other hand, is it possible that the language will asymptotically reach 1.0 because of the slow documentation effort?

Possibly, but it's hard to say, especially when we haven't talked to the core contributors directly. Still, I think the biggest bottle neck is their limited time. Theoretically, one could submit all the necessary PRs to add whatever features we need to get a v1.0. However, it seems that the core contributors would not be able to merge them immediately for lack of time.

That is, could pushing hard on the documentation side encourage and inform what a 1.0 release looks like? For example, perhaps the documentation project will help define what features a 1.0 version of PureScript should have.

I don't see how documentation could help with that: how does documentation relate to type theory? Isn't it the other way around? Also, this somewhat assumes that people don't know which features the 1.0 should have. I think they have an idea of where they are generally going towards. The question is what to include (and wait longer to have) vs what to exclude (and get language stability faster). That might be the real issue.

And, could having a smooth and friendly 1.0 event, perhaps flourished with educational and introductory text by the docs team, grow the new users in a healthy way? Could this healthy influx of new users translate into a growth in long-term users, which translates into new contributors to the compiler, documentation, and libraries?

Such an event could grow the user base, but it would likely lead to problems unless we had a v1.0 of the language first. Those who are currently using PS do so because they've made it past this 'threshold' of understanding. Those who are learning it have yet to decide whether to stick with it long enough to make it past that threshold or not.
I think the influx of new contributors would make the most sense when the language has stabilized, as then documentation efforts and writing libraries would become the greater focus. Moreover, people would not be discouraged from writing libraries because they would know that breaking changes in the language would not create problems for quite a while.

I imagine this documentation project will be a forever project, so it's pretty likely that few people will contribute through its entire duration. Perhaps an important goal for this project, then, is to construct a framework and culture for the language that enables the documentation project to effortlessly or enjoyably grow. I'd like to see it enter a state that would enable you and I to drop out of the project for a few months or years and come back to see it has "naturally" grown and towards a good product. This is one of the reasons that I'd like to take time to reach out to other language maintainerships to learn how they manage their documentation project -- to discover what state we need to reach to enable the initial hard push on the documentation project to relax a bit.

Yeah, I'd say the 'foreverness' of documentation is the case for most languages. I also think being able to pass on the work to other people is more likely to happen if the language stabilizes as one's documentation work will not become as outdated as quickly. Or, perhaps we could use Rust's model of "epochs" to reduce the frequency with which one updates documentation.

This is something I haven't thought of. It's interesting! I've always thought of the PureScript project and its development to a hobby project to most of its contributors. If it's a hobby project, then its main reason people are here is because it's enjoyable. Does this preclude it from being a "successful" project?

I don't think Phil would describe this language as a 'hobby project,' even if he no longer contributes to the language anymore. Likewise, I don't think the other contributors would think that. I think it's become 'the only worthwhile solution' to many web developers who know FP concepts. I'd imagine that contributors would love to work on the language more, but it doesn't pay the bills. I think that's partly why the Open Collective page was started, and it was likely removed for fear that someone would scam the people who pledged to donate towards that effort because there was no single vision indicating how the language should move forward.

Perhaps we can gather what most contributors think a PureScript "success" looks like? Due to varying opinions and goals, I imagine the answers would categorize the contributors into a few groups. Amongst these groups, what would the common aspects of this "success" look like? What are the most important 1 or 2 invariants/principles of each group? This would inform where PureScript can go, which would allow us to derive opportunity cost on our decisions here.

This sounds like a necessary "next step." The issue of 'a lack of a clearly-communicated vision' is a reoccurring pattern in the sources we analyzed.

I feel like having the PureScript project thinking about a shared vision of "success" is akin to thinking about a shared set of values. So, if we do go down this route of having people define a shared set of values, it might be fruitless. It's possible that changing the wording or the context would produce different results, however.

We won't know until we try.

Perhaps this question can be better answered after we finish the Sources phase of this project. Or perhaps just before we actually start down the route of taking the steps of realizing the goals we select. I think "saving" our work here would simply be setting up the structure for realizing the goals of this project, purescript-documentation-discussion, though I might need to think a bit harder before settling on this answer.

I agree that we should finish the sources phase. To me, "finishing the sources phase" means fully writing out the Context/Narrative that explains the current state of PS, which concludes with the decision we will make about whether to continue with this effort, how, and why.

[JordanMartinez]

Also, once the Context/Narrative gets written, I think that would be the best time to then notify the larger community via Slack, Discourse, and Reddit.