(Action after the comment on the “Iterating over a build” page.)
After a bit of thought I realized that merging the two pages together would produce a very long one. Thus, it might be best to clarify the separation between the two topics. In my opinion, a good step forward (and one that could actually solve this problem) is removing the “Iterating over a build” section in this page as it is quite condensed and doesn’t actually help the reader in debugging the different phases that are explained later. The concern I have is that having a section with a header might disguise it as a complete topic while another broader page exists, as well as possibly inducing some confusion on people following the how-to and finding the same title in two back-to-back pages.
My suggestion for this page is removing the “Iterating over a build” section and replacing it with a sentence either at the end of the following paragraph “Build issues are linked to the stage that snapcraft is working through (see Snapcraft lifecycle) when it generates an error, and the most common problems associated with each step are outlined below.” or at the end of the page, saying:
"
Troubleshooting each lifecycle step is made easier by the --debug, --shell and --shell-after options that can be passed to the snapcraft command. For details and other recommendations for a quicker development process, see Iterating over a build.
"
This should provide both the separation in topics between the two pages and a clearer guide for a person that landed on this page to get more information on the debugging practices. (I am aware that “Iterating over a build” is linked in the references, but it might be missed since a similar section is already in this page.)