Figure out how to represent the doc structure

[bendemaree]

I think the CYOA-style dictates a kind of tree structure; each doc chunk either has a single descendant or multiple, so it could potentially be a single linear path, but likely isn't.

However, I could also see a desire for allowing cyclic steps in a doc layout, which makes it more like a directed graph and changes the semantics of it. Then you have cases where there's "related" doc chunks as well as a single path forward, "next"-only doc chunks and paths that could potentially have the user repeating instructions.

You could also potentially allow "related" docs in a tree structure, but if you jump to a "related" doc (as a reference) then there's potentially difficultly in getting the user back into the flow they were in moving through the docs.

I think the best route is probably to use a structure where there's a strictly forward flow and there are no jumps out of the flow...OTOH people will probably want to jump in where they left off.

So, what if there are two main entry points?

1. Start at the beginning, and progress through with only the ability to pick the next section.
2. Allow a returning user to specify the choices they've already progressed through (or know up-front) so they can jump in. That second one might require stricter declarations in the source docs, but could look like:

Already been here? Pick up where you left off:

I am working in [OS X | Linux | Windows ]

user chooses OS X

Already been here? Pick up where you left off:

I am working in [OS X] (Start at this step? Click here)
I am trying to [do general setup | write a test | develop a feature]

and so forth.

To summarize, a few questions:

• 👍/👎 on the tree?
• How will users have to declare these conventions in their docs vs. how much can be done automatically?
• 👍/👎 on the entry points concept?

[kawa-kokosowa]

@bendemaree I really like the issues you're bringing up... here's how I envision handling that...

I agree, a tree model seems to be the best way to accomplish this. So 👍 to the tree.

A page could be an object with these attributes:

• jump_to: a list of sections (by filename) the user may jump to, presented as a list of options
• next: If not None a button appears, defining the next page to jump to

I like the idea of if you came back to a doc later you'd see a summary of which sections you've completed and how you answered.

Maybe in addition to a progress bar, a timeline that'd look like a row with a bunch of boxes, each box having the section title of that section you completed. I ALSO like the idea of the last item (right-most) being faded box with the next section title if available.

[kawa-kokosowa]

I should probably just make a mockup of my idea for a progress thingy.