Improve docs by adding clearer guidance for BEGIN SOLUTION and BEGIN QUESTION

[dlab-frontdesk]

A GSI created a cell that should have been editable by the student in the notebook generated by otter, but it was not editable in the output:

When I try to generate a student version (and auto-grader zip file) from the original file hwk05_advanced.ipynb, the resulting student file is uneditable. There are lines the students should be able to click and add their answers, and it is currently impossible. Additionally, some of the framework for otter-grader that should be made invisible in the student copy is still showing. For example, # BEGIN ANSWER NO PROMPT and everything that follows after should be made invisible for the students, but instead the entire solution is shown. I have compared it to the otter-grader demo file and can find no significant differences, but the demo file produces an editable student copy and my file does not. I even went into the meta data and changed things up, to no avail.

Here is the input notebook:

This is a feature request to please update documentation to more clearly state the #BEGIN SOLUTION requirements when adding a #BEGIN QUESTION and also have otter provide warning when it detects a missing statement (if possible).

They eventually found a solution to the problem from another GSI:

Luckily the other GSI I work with found the solution. It seems that otter-grade requires two calls to begin and end a solution. So for example I had #BEGIN SOLUTION NO PROMPT, but it requires #BEGIN SOLUTION before that, in a raw cell. For some reason.

From the documentation as currently written it's not obvious to me that this is a requirement to get the cell to be editable, and it would be helpful to provide guidance about the "failure mode" if it is missing, where the cell won't be editable if the other statements are not included. When I searched for the word "editable" in the docs, nothing useful came up to help us troubleshoot.

https://github.com/ucbds-infra/otter-grader/blame/52dca8c745332e89e12fb417b12aa686e9f34a4d/docs/otter_assign/notebook_format.rst#L317-L334

[aculich]

ps. I submitted this from @dlab-frontdesk so adding myself in the thread so I get replies directly to me, as well.