When @tomdale and I started iterating on Guides materials, we made the decision to make guides focused and succinct rather than in-depth explorations of their topics.
Occasionally we get contributions that address particular concerns or confusion that individual readers have with the guides. The tradeoff in accepting these contributions is we slowly drift away from our original goal of succinctness.
No single commit, of course, does this. There is the concern that over time these commits will decrease guide clarity and, since we arrive at the point haphazardly, not be especially good in-depth guides either.
So, moving forward, what should we do? Some options:
- Recognize that we cannot remove 100% confusion for 100% of people, keep the guides focused, and leave non-essential information to blogs, books, and SO questions.
- Abandon the short guide approach and consciously enact a plan to become in-depth guides like Rails Guides.
- Keep the short guides and add companion More Information Than You Require guides.
- Split each guide page into two sections: basic and extended.