SimDem2 Proposal: Table of Contents

[lastcoolnameleft]

This is intended to be an open discussion how what approach SimDem should take:

How should SimDem work with a tutorial with a lot of steps. As new files are added, renamed, moved around, it would be painful to auto-update all files

An example is my personal workshop that I'm using to test SimDem.
https://github.com/lastcoolnameleft/workshops/tree/master/kubernetes

Updating the "next steps" would be painful. https://raw.githubusercontent.com/lastcoolnameleft/workshops/master/kubernetes/index.md

What if we were to use a convention like a "toc.md" file stored in the directory that manages the flow of the tutorial?

[SorraTheOrc]

Yes, I've hit this problem myself. Thought I've not put a great deal of thought into how to handle it.

I'd be tempted to go for simple first and let it evolve as needs demand. The Next Steps idea was originally more of a ToC than a post document navigation. It was created to provide the ToC at the start of the SimDem documentation and later repurposed to the Next Steps. This worked well, for a while, then it hit the management issues you refer to.

I would support going "backwards" and doing as you say, have the ToC drive the next steps. We'd lose the "pick your own adventure" model of tutorial/demo design, but we can always bring that back later if needed.

[lastcoolnameleft]

After some time to let this idea simmer, here's my proposal:

• If exists, parse a ToC section from the page specified in the CLI
• This ToC becomes the "next steps" for all subsequent steps the user might follow.
  • Allow the user to go forward or backwards
  • This prevents documentation drift of multiple ToC/Next Steps (!!!)
• If another ToC exists in a subsequent page, it ignores it.
  • In the future, we could have it override the current ToC, but that's a story for a different day.

[lastcoolnameleft]

Feature Implemented: https://github.com/Azure/simdem/commit/14b2fafdd32ad3817181c37b4a90d2296f9138d2

@rgardler Let me know if you have any concern with the implementation.

[SorraTheOrc]

LGTM