PureScript documentation efforts in 2019

[JordanMartinez]

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

Well, it got merged now (hurray!).

[chexxor]

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.

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?

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.

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?

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.

[JordanMartinez]

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.

[chexxor]

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

[JordanMartinez]

Great. Let’s get started!