Common usage documentation #195
Description
api_spec.md has a lot of content, but doesn't always describe the intended usage of certain components.
For example, state["current_subtask"] should really only be used by a few internal functions, everything else should use get_current_subtask_key() (or get_current_subtask()).
Similarly, annotations shouldn't be marked "deprecated" directly, they should use mark_deprecated() (see #194).
Some of this "common usage" or "best practices" should be documented in a single spot, to avoid confusion and prevent future bugs.