Ordering of pages in the tutorial seems incorrect

[keck-in-space]

When reading the Error Handling 2 section, it suddenly goes back to Unit Testing 5 at the end of this page: https://fprime-community.github.io/fprime-tutorial-math-component/docs/error-handling-2.html

Should unit testing 5-7 be part of the existing Unit Testing section? It was a bit confusing when the sections appeared out of order.

[thomas-bc]

I believe splitting the sections up was a conscious decision by the original author. Slowly build things up, and reuse what you just built in other sections. Although I'm not entirely sure about this specific case.

[bocchino]

I agree that the ordering of sections seems jumbled. For comparison, here is the original layout of the Math Component tutorial from the first release of FPP:

https://github.com/nasa/fprime/blob/v3.0.0/docs/Tutorials/MathComponent/Tutorial.md

In the original version, the error handling material was in a separate subsection of the Math Receiver section, and not in the middle of the unit testing section.

A related issue is that it is hard to know where you are in the tutorial when you land on a page. For example, the page linked above is in the middle of Section 6 (I think). Nothing on the page indicates that. It would help to have previous and next buttons on each page, and a more complete table of contents to see the structure.

[keck-in-space]

Thanks everyone. We typically use mkdocs with the mkdocs-material theme for internal documentation, which fixes the "where am I?" issue.

I took a stab at implementing it for this tutorial on my fork just as an example. Here's the rendered page if you want to see what it looks like: https://keck-in-space.github.io/fprime-tutorial-math-component/

Mkdocs also adds search, (optional) dark mode, and a TOC for each page.

[bocchino]

Thanks, looks good! The organization is better, because the unit testing material is now all together, and the error handling is in a separate section.

The mkdocs format looks great. The structure of the tutorial is much clearer in this format. The search box provides a capability that someone asked about at a recent F Prime workshop. I think this proposal should be part of a larger discussion on how to improve the formatting of the F Prime docs.

If you want to implement these changes, then I recommend the following:

1. Make a PR with just the changes to the organization and cross-links, keeping the current format for now.
2. Start a discussion on doc formatting on nasa/fprime: https://github.com/nasa/fprime/discussions.

[bocchino]

For example, the page linked above is in the middle of Section 6 (I think).

My revised opinion is that linked page is in Section 8, but the cross-links pop out of Section 6, traverse sections 7 and 8, and then go back into Section 6. This definitely needs to be fixed.

[thomas-bc]

@keck-in-space thank you so much for taking the time to bring this up, I really like the navigability of it as well. We will most definitely look into mkdocs.

[keck-in-space]

Thanks for the comments! I opened a PR (#28) with the navigation fixes on this repo, and also opened a discussion here: nasa/fprime#2635