Add espflash troubleshooting page and 26MHz crystal issue

[bugadani]

Relevant issue in espflash: esp-rs/espflash#410

I think the issue may warrant its entry in the list of troubleshooting tips.

I'm honestly not sure what the solution is for esp-hal based projects - they don't build a bootloader.

[SergioGasquez]

I'm honestly not sure what the solution is for esp-hal based projects - they don't build a bootloader.

They may need to build a bootloader anyway using an esp-idf C or Rust project. We could think about including an esp32_26MHz bootloader in espflash, but they would still need to download it and use it with the --bootloader arg.

Regarding moving troubleshooting to a section, we had it like this in the past, but our colleague from documentation team @f-hollow recommended us to avoid that.

[bugadani]

recommended us to avoid that

Unfortunately it's not possible to nest appendix pages in mdbook and I couldn't find an alternative solution other than moving it back.

[jessebraham]

Regarding moving troubleshooting to a section, we had it like this in the past, but our colleague from documentation team @f-hollow recommended us to avoid that.

Is there some documentation somewhere which states the guidelines being suggested? This is not the first time I've seen a suggestion that frankly makes no sense to me, so I'd like to better understand where this is coming from.

[SergioGasquez]

Is there some documentation somewhere which states the guidelines being suggested? This is not the first time I've seen a suggestion that frankly makes no sense to me, so I'd like to better understand where this is coming from.

Not that I know of, maybe Kirill does have some documentation about this. IIRC, the point was that troubleshooting is usually a kitchen sink with various "random" stuff on it, the equivalent of the utilities modules in code, and it would be better to include the information in the relevant chapter with more context where we can help the user avoid the error instead. That was the reason, again, IIRC, for keeping the troubleshooting as a small appendix not very related to the book

IMHO, FAQ/Troubleshooting are useful, and we can have it as a section since many people won't read documentation, so you can just share a link and dont need to repeat yourself many times.

[Vollbrecht]

We always build the bootloader in esp-idf-sys - but by default not using it. Though if you are a user of cargo espflash you are automagically using it. We currently have an PR that was just merged in esp-idf-sys master that will automatic copy the bootloader (also the partition table) into the project dir after its build to make it easier to find - instead of searching through the target/build dir

[SergioGasquez]

Not sure if the PR is ready for review, but here are a few nitpicks comments, other than that, it LGTM!

[bugadani]

Not sure if the PR is ready for review

Now it is :) thanks for the suggestions!

[f-hollow]

Is there some documentation somewhere which states the guidelines being suggested? This is not the first time I've seen a suggestion that frankly makes no sense to me, so I'd like to better understand where this is coming from.

Not that I know of, maybe Kirill does have some documentation about this. IIRC, the point was that troubleshooting is usually a kitchen sink with various "random" stuff on it, the equivalent of the utilities modules in code, and it would be better to include the information in the relevant chapter with more context where we can help the user avoid the error instead. That was the reason, again, IIRC, for keeping the troubleshooting as a small appendix not very related to the book

IMHO, FAQ/Troubleshooting are useful, and we can have it as a section since many people won't read documentation, so you can just share a link and dont need to repeat yourself many times.

Sorry, I am bit late for the party!

@SergioGasquez conveyed the reason very well. From what I remember, the Troubleshooting section was a collection of unrelated topics detached from the context and without any references. Usually, it means that the users are quite unlikely to discover such information when they need it. This is why, for example, tech writers try to avoid FAQs these days for exactly the same reasons.

As a tech writer, I usually do the following:

• Place troubleshooting information where the users might encounter the issues.
• If a separate Troubleshooting section is more convenient for whatever reason, I try to add links or references.

So I proposed to move Troubleshooting to Appendix as a temporary measure before you find ways to properly integrate this information with the rest of the book. Regarding the placement of Troubleshooting in general, it can be anywhere as long as the flow of the book is not affected and the information is discoverable.

Basically, these guidelines are applicable to any information, not just Troubleshooting, so I am not sure if I can point to any established guidelines about where to place Troubleshooting.

@jessebraham @SergioGasquez As I am not a software engineer, I might be missing some important points here. If you see any flaws in my logic, I will be glad to hear your arguments. Thank you!