Skip to content

Commit 04c06d3

Browse files
Add headers and outline for next parts of the file
1 parent 186e20f commit 04c06d3

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
170199
The 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

Comments
 (0)