PureScript documentation efforts in 2019


#21

Well, it got merged now (hurray!).


#22

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. :slight_smile:

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.


#23

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.


#24

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


#25

Great. Let’s get started!