Docs: Managing multi-file tutorials

[Cheetham, Anastasia]

I'm hoping the community can weigh in on ideas for managing multi-file tutorials in our new Markdown documentation repository:
    https://github.com/fluid-project/infusion-docs

Justin has a pull request that includes the "Getting started with Infusion" tutorial, which comprises multiple pages. The Preferences Framework "Creating a Preferences Editor Using the Preferences Framework" tutorial is ready for conversion to Markdown; it, too, comprises multiple pages.

I'm worried about a proliferation of files that are strongly related to each other just hanging about together at the root of the repository. It's confusing to work with, and I imagine it might be confusing to our users.

I'd like to propose some possible approaches to better organization:

Proposal 1
----------
a) All files related to a given tutorial should be contained within a single folder named according to the tutorial, e.g. "Tutorial-GettingStartedWithInfusion"
b) Files within the tutorial would NOT have "Tutorial" in their names.
c) Any file in a multi-file tutorial must have a note that identifies it as part of a tutorial, with a link to the start of the tutorial.

Proposal 2
----------
a) All tutorials must be self-contained in a single file.
b) The file name would start with "Tutorial-"


What do people think of these proposals? Does anyone have any other suggestions?


-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocadu.ca           Inclusive Design Institute
                                        OCAD University