= !SasView Tutorials: The Next Generation = == Background == We need to replace the dated and monolithic (!SasView 2.x) Tutorial [https://github.com/SasView/sasview/blob/master/sasview/media/Tutorial.pdf (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: * http://trac.sasview.org/ticket/387 - Need new tutorial documentation * http://trac.sasview.org/ticket/516 - Add Pr Tutorial module * http://trac.sasview.org/ticket/517 - Add Invariant Tutorial Module * http://trac.sasview.org/ticket/518 - Add 1D model fitting tutorial * http://trac.sasview.org/ticket/519 - Add 2D model fitting Tutorial * http://trac.sasview.org/ticket/520 - Add constrained fit Tutorial * http://trac.sasview.org/ticket/521 - Add simultaneous fitting tutorial * http://trac.sasview.org/ticket/522 - Add Batch Fitting Tutorial Some of the 'next generation' material will require our !SasView documentation build processes to produce PDF files. Tickets relevant to this are: * http://trac.sasview.org/ticket/510 - Build PDF documentation along with HTML * http://trac.sasview.org/ticket/927 - Add !LibreOffice to Build Servers * http://trac.sasview.org/ticket/934 - Slurp tutorial repo for tutorials * http://trac.sasview.org/ticket/935 - Build new tutorials as PDF Once !LibreOffice is installed on the Build Servers it will also be straightforward to output the 'next generation' material as HTML and eBook. Tickets relevant to this are: * http://trac.sasview.org/ticket/936 - Build new tutorials as HTML * http://trac.sasview.org/ticket/937 - Build new tutorials as eBook The issue of 'tutorials' has previously been raised on this Wiki at: * http://trac.sasview.org/wiki/Documentation%20Work%20Package (first created Jan 2015) * http://trac.sasview.org/wiki/Rework%20Proposal (first created Mar 2016) Wojciech has also made some suggestions regarding frameworks and infrastructure for new tutorial material in [https://github.com/SasView/documents/blob/master/Development/Tutorials/DAM-SasViewtutorial-040417-1545-114.pdf 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 [http://www.sasview.org Website] - which has a good FAQ page created from actual questions from Users & links to other resources * the !SasView [http://trac.sasview.org 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: * [https://www.oxygenxml.com/ Oxygen XML Editor] * [https://www.libreoffice.org/ LibreOffice Writer] - this is what used to be Open Office Both of these are WYSIWYG and both provide output in a 'flat' Open XML format which would allow git to do difference-checking for version control purposes. But only !LibreOffice is free. Steve & Andrew tested git with a !LibreOffice Writer .fodt file that they both independently edited and git behaved as expected. ''Recommendation: We should use !LibreOffice Writer to generate Tutorial documents saved in .fodt format'' == Getting Started == Click [http://trac.sasview.org/wiki/TutorialsTNGForAuthors here] for the current list of Tutorials and instructions on how to write and contribute them.