Proposal: Remove requirement/current state to begin every header with "How/Why/When do I"

[lwjohnst86]

Proposal

Related to discussions about what the book is: Is it a reference book or is it a course? From my impression, this is a course, so I propose we not be required to have every header start with "how do I" since it restricts the ability to go with how the course may flow.

Background

Based on several discussions (e.g. #319), there is a bit of confusion about if we are creating something like would be used in a course or if it is a reference document. This leads (at least for me) to some difficulty in writing/structuring the content and aligning it with exercises. Part of the issue (at least for me) is all the sections are named starting with "How do I...".

If it is a reference book, having "How do I..." headers makes sense, since it is easier to jump to a section and read up on the topic from there. This approach makes a lot of sense if the learner is knowledgeable or aware of the "How do I" topic. The target audience of reference books are people with some knowledge on the topic, but not for novices to the topic.

If it is a course, courses require alignment, a flow of sequences that build off of previous content and exercises, and broadly named and generic section topics. Sections are named and structured based on previously completed tasks as the content and exercises build off of and expand on one another. Having every section named by "How do I" is confusing (to me), since a course topic session doesn't always fit nicely into a "How do I" structure, nor should they... as mentioned above, a learner may not even know what the second part of the "How do I" is. As it is, some sections don't have exercises because the section title doesn't really allow exercises to be created.

For example, in the testing chapter there are two sections "How do I create and run unit tests?" and "When should I write my tests?". The "when should I" topic doesn't really allow exercises to be included in the section. But if an overall section was called e.g. "Writing unit tests", then the content could include when and how while also allowing exercises to be included within it.

If, as we've discussed in e.g. #319, these books are designed as a course, than I suggest we remove the current status of each header starting with "How do I".

See related discussion at #319, #240, #199, #282, #128, and #43

Pros and Cons

Pro:

• We're already doing a major revision to focus on alignment and on Python only, so it won't take much more to rename headers to fit the overall narrative of the course and the individual chapter/section.
• It flows better for a course setting, since the contents of the header can be merged in under broader "section names"
• It'll be easier to maintain alignment and structuring of sections and exercises, since overall sections can be named more broadly and so more related topics can be grouped together.
• It'll be easier to link section material with exercises since there isn't a restriction on how the header name is set.

Con:

• It could be easier to leave it as is since we already have them written up.
• Chapters may likely be less "modular", though it could be minimal depending on how we structure the start of each chapter.

[k8hertweck]

I'm glad for this opportunity to take a second look at how we're phrasing headers, and regardless of whether we move from a question-based format (e.g., "How do I write code?") to static descriptors (e.g., "Writing code"), it's worth taking another look at consistency and clarity. It seems like some of the concerns noted in this proposal, such as questions including terms that haven't been introduced, can be alleviated by reframing questions. In my example above, it would be equivalent to "What is code and how do I write it?" Similarly, the example noted by @lwjohnst86 about unit tests could have headers reframed: the second-level header is "How do I create and run unit tests?", with third-level headers "About unit tests," "When to write unit tests", and "How to run unit tests." Related questions include:

• Do we generally support third-level headers? Currently it looks like second-level headers are all questions, and third-level are topics, but the latter aren't frequently occurring.
• Are we interested in at least somewhat consistent lengths of sections? Adding third-level headers could help add some more structure and bridge the gap between reference and teaching philosophies.