Docs: Managing multi-file tutorials

[Antranig Basman]

Remember that we will have in time a static publishing solution that will manage the weaving of our 
documentation into appropriate integrated forms. It is much easier to join together files which have been 
split rather than split files which have been joined. We should go with proposal 1 in this case, and deal 
with weaving the files together later. We should make sure that we adopt a naming convention that makes the 
sequence of the files easy to deduce from the filename.

Cheers,
Antranig

On 10/06/2014 19:01, Cheetham, Anastasia wrote:
>
> 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?
>
>