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