@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.