[EDIT]First draft of Introduction is now open for comment[/EDIT] [EDIT2]The revised architecture diagram is now open for comment[/EDIT2]
The Big, Strange How-To has been the standard (and, er, only) textbook on Strange since its inception. But with the exception of a handful of corrections and the addition of a couple of new features, it has remained largely unchanged since it was first written way back alongside v0.5. With the upcoming release of v1.0, I reckon that it’s high time for a proper update.
With the benefit of hindsight and whisky, I’m looking at everything in the BSHT to see what needs updating, adding, or even removing. And that’s where you come in, my friends!
What could we explain better? What has frustrated you most, especially when you were first learning? I especially want to concentrate on the new user: what can we do to flatten the steepness of our learning curve?
Here are my ideas so far. Please leave comments below and I’ll keep this post updated with your input.
Things to add to the Big Strange How To
Re-work the Introduction
- Make the tone easier and more approachable
- Add a reference to list of supported platforms
- Add reference to Is Strange Right for You?
New section: opening Strange for the first time (walk-through)
- Explain the broad structure of the repo.
- Walk-through of MyFirstProject project
- Walk-through of MultipleContexts project
Updated section: Signals
- Beef up the Signals section.
- Add explanation for the (new to v1.0) ListensTo feature.
- Change all examples (across all of BSHT) from EventDispatcher to Signals.
Updated section: Mapping across Contexts
This section is really thin. Let’s clarify the concept and the execution. Particularly, explain the reasoning behind multiple Contexts, along with practical info on how to structure them.
Updated section: Reflection
I don’t want to confuse a new user with too much about this…but then the understanding the principles is important.
New section: Pools
Explain how the Pools extension works
New section: Promises
Explain the (new to v1.0) Promises package
New section: Implicit Bindings
Explain the ImplicitBind package
New section: runtime bindings
Explain the (new to v1.0) feature runtime bindings
New mini-section: Strange for extending Unity
A mini-section because it will essentially just link to a separate document specifically about using the (new to v1.0) Editor extension. The current plan is for the Editor extension to live outside the main Strange repo as an optional plug-in.
New section: Testing tutorial
Explain how to run unit tests and write your own.
Enumerate Exceptions for each package
In each package, list and explain each of the thrown errors. In an appendix at the end of the document, put all Exceptions in one place for easy reference.
All that pesky text art (—–>). Let’s grow up and use PNGs or SVGs or something.
Lots of people asking for something more like a step-by-step tutorial. Particularly questions about uGUI. Should this be here or a separate document?
New Section: Platform Specific Issues
A request in the comments to explain iOS trampolines. Compile a set of other platform-specific gotchas?
New Section: Best Practices
Some cohesive section on Dos/Don’ts when using Strange.
Add named injection for constructors
How this will work
I’ll going to create the new BSHT as a Google Doc at first. I’ll edit this post and provide a link so everyone can weigh in. In the meantime, feel free to leave comments and ideas.