BSPIMX8M-3139: create PD24.1.0.rst BSP manual

[ymoog]

For upcoming imx8mp mainline BSP release, add a manual. This is done because the content and structure may be different from vendor releases. Since the plan is to move back to vendor release after the mainline release, we do not work on the head manual and branch off early.

Add some misc. improvements that I noticed during proofreading.

Depends on #145

[ymoog]

I think that customers could be confused by thinking that PD24.1.0 has been released already. Can we make this more obvious that is an unreleased BSP? Remember that everything gets published immediately, which was not the case before with our confluence setting.

Like e.g.:

* Adding a red warning box at the beginning of the manual. Maybe we can even refer to a doc that explains how customers could checkout this WIP BSP for testing? After all, whenever the reader consult Docs for released BSPs, they see those new and unreleased BSPs in the sidebar and that might raise their interest (which is a good thing I guess).

* Changing the manual Name to PD24.1.y from PD24.1.0. Once we release the manual we can change this.

What do you think?

I agree it is a challenge to avoid confusion.

My suggestion is the following:

1. Create "feature" branch where all PR are merged to.
2. Use normal workflow for working on pd24.1.0
3. Upon release, merge feature branch into main -> tag it.

Then, no pd24 will be public at all. We have a pd24 draft that we can continously develop until release. After release the feature branch is deleted so no complexity regarding multiple branches.

[jonas-rem]

Generally I like the idea of drafting the manuals of unreleased BSPs in the open. We also develop them in the open and customers can test them anytime. And if they test BSPs, a draft manual is a great advantage.

Of course they have to be aware of this, so a prominent marking of draft bsps should be sufficient IMO.

Edit: The disadvantage with branching is that is still increases complexity during developing. E.g. this increases complexity in the case, where a developer finds an error with older BSPs while writing on the draft release. Working on the main branch makes it easy to fix the error/strcture globally.

[jonas-rem]

[..] because if we released this to public, customers would probably expect everything in the manual to work, which is not the case. That could lead to more questions for the FAE/support, which we should probably avoid.

Yes, you have a point here. But with our current approach, the upcoming release is already being public (HEAD Documents). Several weeks back with the PD23.1.0 imx8 release, we linked this documentation in the Phytec Website for the first time. So at this point we probably can not yet tell if there are more questions for the FAE team because of the published HEAD Documents.

The new decision here is whether we want to have a second HEAD document for a mainline release for now, as this allows a dual approach i.e. alternating mainline and NXP releases. And to make it really clear to customers, we could call it HEAD_MAINLINE or so instead of PD24.1.y unless officially released. We could move to branches anytime, once we see support traffic going up.

If you find this too risky and expect many questions for unreleased BSPs, we should probably hide all HEAD documents in branches.

[ymoog]

If you find this too risky and expect many questions for unreleased BSPs, we should probably hide all HEAD documents in branches.

I renamed the pd24.1.y file, but kept the doc-id for now (since we also have the PD24.1.y manifest).

[ymoog]

Sorry @jremmert-phytec-iot didn't refresh the page.