@@ -167,6 +167,35 @@ Here's what has been added to the above since then:
167167| A Guide to the PureScript Numeric Hierarchy | Explanation | New Learners | Read the Docs
168168| Make the Leap from JavaScript to PureScript | Getting Started + Explanation | Javascript developers | Blog Post series
169169
170+ ## Why is PureScript's Documentation Lacking and How Do We Improve It?
171+
172+ - Philosophy of the language:
173+ - avoid (success at all costs)
174+ - wrong intepretation:
175+ - right interpretation
176+ - Current priority of core contributors: adding powerful features via breaking changes
177+ - wrong interpretation: they don't care
178+ - right interpretation: want to improve language
179+ - Why a ` v1.0 ` hasn't been released
180+ - Core Contributors are spread thin, so they cannot respond quickly to things
181+ - The '75 libraries' problem
182+ - Entrusting library maintenance to others and supporting them (e.g. the ` event-stream ` incident)
183+ - Just like reviewing code, reviewing documentation takes a lot of thought
184+ - Hard to keep documentation momentum
185+ - Which libraries are 'core libraries'?
186+ - No clearly-defined mutually-held community-wide goal
187+ - A desire to help exists, but no one is coordinating resources strategically
188+ - What exactly are FP's "Best Practices?"
189+ - They are not well-defined, are assumed, or are habits
190+ - Knowledge silos exist, so it's hard to extract that info
191+ - Slack-based discussions do not persist
192+
193+ ## New Learners: What is the Best Way to Learn PureScript?
194+
195+ ## PureScript Documentation Writers: What is the Best Way to Write Documentation in this Context?
196+
197+ ## Core Contributors: ???
198+
170199The following
171200 - Evaluate PureScript's documentation using that criteria
172201 - Explain why PureScript's documentation is lacking and what is being done to improve it
0 commit comments