Version 21 (modified by smk78, 8 years ago) (diff)

—

SasView Tutorials: The Next Generation

Background

We need to replace the dated and monolithic (SasView 2.x) Tutorial ​(here) that presently ships with SasView 4.x with new materials that are fresh, engaging, and modern.

Several existing tickets relating to the provision of 'tutorials' are now captured on this wiki page and the corresponding tickets closed:

Some of the 'next generation' material will require our SasView documentation build processes to produce PDF files. Tickets relevant to this are:

The issue of 'tutorials' has previously been raised on this Wiki at:

Wojciech has made some suggestions regarding frameworks and infrastructure for new tutorial material in ​this document

The Bigger Picture

Any tutorials we produce will be part of a bigger portfolio of 'documentation' comprising:

  • the in-program Help (actually called 'Documentation' in SasView itself) - this is invariably the first place any Sasview User looks for answers
  • the Tutorials themselves
  • the SasView ​Website - which has a good FAQ page created from actual questions from Users & links to other resources
  • the SasView ​TRAC site - primarily for the Development Team, but a lot of content should be accessible to 'advanced' Users

Whilst there will be some cross-over between these different strands they should not seek to duplicate material unnecessarily.

So What Is A Tutorial?

A Tutorial is self-paced instruction that provides a step-by-step approach to some learning unit.

It should be interactive, visual (and/or possibly audio), goal-driven, and provide some form of feedback or test of learning (such as through question-answer exercises and/or providing access to comparative results).

The Need For A Philosophy

The problem with the Tutorial definition above is that it potentially encompasses a wide range of delivery mechanisms. Within the SasView project we are, of necessity (given our available resources), going to need to focus on providing the key material in the most accessible form. That means Tutorial documents in HTML, PDF, and possibly (since the production overhead should essentially be zero given the first two) eBook formats.

Anything else simply cannot be a priority for us at the moment. It could, however, be provided by enthusiastic members of the Community if they so wished…

The Tool For The Job

If we agree that we shall provide some Tutorial documents then, to ease production, maximise buy-in, and encourage Community contributions where applicable, we need a production platform that is free(!), intuitive (ie, WYSIWYG), and suitable for version control using TRAC. (The current Tutorial is written in Microsoft Powerpoint which only meets one of these criteria).

After looking around Andrew identified two possibilities:

Both of these are WYSIWYG and both provide output in a 'flat' Open XML format which would allow TRAC to do difference-checking for version control purposes. But only Libre Office is free.

Steve & Andrew tested TRAC with a Libre Office Writer .fodt file that they both independently edited and TRAC behaved as expected.

Recommendation: We should use Libre Office Writer to generate Tutorial documents saved in .fodt format

Tutorial Template

Click ​here to download a Tutorial template for Libre Office Writer. Don't forget you will need to install Libre Office as well! :-)

Contributing a NEW Tutorial

Here are some simple steps to contributing a new Tutorial:

  • Download the Tutorial template above
  • Rename the template to something descriptive of the Tutorial you are about to write (but keep the filename manageable!)
    • filenames must be lowercase
    • separate words in filenames by underscores, nothing else please
    • keep the file extension as .fodt
  • Open your Tutorial file
    • on Page 1: give your Tutorial a title
    • on Page 2: add your name and email address to the list of contributors
    • on Page 3: state the Objective of the Tutorial
  • Write your Tutorial!
  • Save your Tutorial

What you do next depends on whether you think you will need to edit your Tutorial (or any other Tutorials) in the future:

  • I do not want to edit Tutorials:
    • simply email the Tutorial to tutorials@… - if it is a rather large file it might be an idea to zip it first!
  • I do want to edit Tutorials:
    • if you do not already have one, create yourself a ​GitHub account
    • login to GitHub
    • in the search box at the top of the window type 'SasView/tutorials' (without the quotes!) and press return
      • you should now be looking at the Tutorials repository; there will be a file called README.md and a green button above it which says 'Clone or download'
    • click on the button marked 'Upload files' to the left of the green button
    • drag-over or choose the Tutorial file you want to upload
    • in the narrow box under the heading 'Commit changes' add a short title for your upload; eg, 'Added tutorial on X'
    • (optional) if you want you can add a more detailed description of what you are uploading in the bigger box
    • click the green button marked 'Commit changes' to add your Tutorial file to the repository

Editing an EXISTING Tutorial

IMPORTANT! Once a Tutorial file is in the repository it is available for anyone to work on and make changes. Provided all authors pull a copy of a file from the repository, make their changes, and then push the changed file back to the repository, Git will ensure that one authors changes are not compromised by another authors changes.

  • To pull a Tutorial file from the repository:
    • login to GitHub
    • navigate to the 'SasView?/tutorials' repository
    • click on the Tutorial file you wish to edit
      • the document contents will be displayed; in the case of a Tutorial file this will be a lot of XML!
    • click the button on the right marked 'Raw'
    • right-click anywhere on the page and choose 'Save as…'
    • save the Tutorial file (as type 'OpenDocument? Text')
  • Edit the Tutorial!
  • Save the Tutorial!
  • To push the Tutorial file back to the repository:
    • login to GitHub
    • navigate to the 'SasView?/tutorials' repository
    • click on the button marked 'Upload files' to the left of the green button
    • drag-over or choose the Tutorial file you want to upload
    • in the narrow box under the heading 'Commit changes' add a short title for your upload; eg, 'Changed/added X to the tutorial on Y'
    • (optional) if you want you can add a more detailed description of what you have changed in the bigger box
    • click the green button marked 'Commit changes' to add your Tutorial file to the repository

Tutorials & Authors

The following table lists required and requested tutorials, their authors, and production status:

TutorialTypeAuthorStatusComment
Simple 1D Fitting
Simultaneous 1D Fitting
Batch & Chain 1D Fitting Should include Combined Batch Fitting
Using Constraints
Working with Polydispersity Functions
2D Fitting
Fitting Magnetic SANS
P® Analysis
Invariant Analysis
Correlation Function Analysis Steve
Writing a Plugin-Model
Working with Image Data Using the Image Viewer Tool
Simulating 2D SANS Data Using the Generic Scattering Calculator Tool
Understanding Orientation Angles
etc