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
[email protected] Inclusive Design Institute
OCAD University
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
