-
Notifications
You must be signed in to change notification settings - Fork 105
Home
Patrick edited this page Jan 29, 2021
·
25 revisions
Welcome to the Wiki, where you can read the Q&A style help or learn about the vision of this project!
Much of the content of the Wiki originally lived in the readme. Initially, it made sense to consolidate all the documentation on the readme as the readme is easily accessible and could be updated alongside the code. However, the process became burdensome as the plugin grew in features and complexity:
- There is a tension between providing comprehensive documentation and keeping the readme easy to scroll through.
- No matter how succinct I tried to keep each section--even at the cost of important details--it was becoming difficult to quickly find what one is looking for.
- A long readme that can't be finished in one sitting is intimidating for prospective users.
- Most people reading the git log for the latest changes likely find non-feature-related diffs and commits changes distracting.
- Having to commit and push adds friction to the process.
- Making updates to the front page of the repo makes writing English more anxiety-ridden for me than releasing new features.
- A Wiki naturally lends itself to organizing all the thoughts I want to write down.
- A lot of what I wanted to explain to users is not documentation per se (e.g. FAQ and design philosophy).
- Finally, I obsess over my words and find myself to writing and rewriting every sentence again and again.