Skip to content

Conversation

@tremho
Copy link
Contributor

@tremho tremho commented Aug 13, 2025

This PR introduces multiple points of entry into the overall documentation depending upon what "track" of interest a reader may have according to their subject of interest or their primary development role.

This re-introduces the concept of multiple markdown "books" being created, similar the original "bookshelf" construction, but the goal here is not to produce a virtual bookshelf of related subjects, but to offer different curated "tours" of the overall documentation, streamlining the journey for those that may not need to read the entire book.

Mdbook does not allow repeated references to the same page in the same book, so multiple books are necessary to allow these selective repeats. The publish bat and yml files handle this by copying pages from the main "guide" into the "tracks" content where needed. Additionally, a few new pages are in "tracks" to provide continuity.

Also added to the main book is a new "architecture" section that features a number of diagrams.

The book is set to flow from the beginning, and a developer-minded reader is advised to read the book from beginning to end, while other interests are advised which sections they might elect to skip over.

Existing links to this content

Because there are now multiple books, the url paths to the content has moved slightly. Page paths for the main book no longer come from the root, so any previous link to "https://opendevicepartnership.github.io/documentation/~path~" will now need to include "guide" in the path, ("https://opendevicepartnership.github.io/documentation/guide/~path~") The index page at https://opendevicepartnership.github.io/documentation/ will still work -- it is redirected to https://opendevicepartnership.github.io/documentation/guide/index.html.

The "getting started" page that I believe is currently linked to at https://opendevicepartnership.github.io/documentation/intro/welcome.html
should be changed to
https://opendevicepartnership.github.io/documentation/guide/intro/getting_started.html
to represent the new arrangement.

Note that prior to merge and publishing, a preview publish for this can be found at https://tremho.github.io/odp-documentation/

Work item tracked in this Project task

Steven Ohmert added 30 commits July 16, 2025 16:48
individualized tours of documentation content by subject or role.
individualized tours of documentation content by subject or role.
individualized tours of documentation content by subject or role.
individualized tours of documentation content by subject or role.
@tremho tremho requested a review from a team as a code owner August 13, 2025 17:53
williampMSFT
williampMSFT previously approved these changes Aug 14, 2025
@williampMSFT williampMSFT merged commit 925d2e9 into OpenDevicePartnership:main Aug 14, 2025
@tremho tremho deleted the multiple-entry-points branch August 14, 2025 22:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants