IBMStreams/tutorials

Many different versions of the intro to spl lab pdfs

chanskw opened this issue · 2 comments

chanskw commented

In our repository, there seem to be many different version of the pdfs:

Streams 4 Lab Guide 1.1a qse.pdf Streams introductory lab installer and lab guide 9 months ago
Streams 4.1 Lab Guide 1.0a qse.pdf Lab and guide updated for 4.1 4 months ago
Streams 4.1 Lab Guide 1.0c qse.pdf Updated for Streams 4.1.1 2 months ago
Streams 4.1 Lab Guide 1.1a qse.docx Streams 4 1 1 b 19 days ago
Streams 4.1 Lab Guide 1.1a qse.pdf Streams 4 1 1 b

This can become very confusing for any new user. Would it be possible to keep a single version of the pdf and rely on the versioning support for Github to keep track of the different version?

Fro example, what's the difference between 1.0a, to 1.1c ?

ulemanstreaming commented

I agree that the versioning and file naming are confusing. Part of it is that I don't understand or haven't taken the trouble to figure out how to use GitHub to manage versions of a Word doc and its derived ("compiled") PDF artifacts. So instead I treat each version as a whole new file, the way I've been managing it on my Windows disk. (If I had been smarter, I would have used a version control system from the start.)

So here's the current mapping.

Installer            Lab Guide                            Description                                       When (as of 5/2/2016)
IntroLab_4.1.1b.zip  Streams 4.1 Lab Guide 1.1a qse.pdf   Streams 4.1.1 b                                   19 days ago
                     Streams 4.1 Lab Guide 1.1a qse.docx  (Source file for editing purposes)
IntroLab_4.1.1.zip   Streams 4.1 Lab Guide 1.0c qse.pdf   Updated for Streams 4.1.1                         2 months ago
IntroLab_4.1.zip     Streams 4.1 Lab Guide 1.0a qse.pdf   Lab and guide updated for 4.1                     4 months ago
IntroLab_4.0.1.zip   Streams 4 Lab Guide 1.1a qse.pdf     Streams introductory lab installer and lab guide  9 months ago

Notes

  • Installer naming: IntroLab_<major>.<minor>[.<mod>].zip
    • <mod> is omitted when 0
    • 4.1.1 and 4.1.1b are both good, but b eliminates the workspaces, in favor of a simple project import to continue with next part.
  • Lab Guide naming: Streams <Smajor>[.<Sminor>] Lab Guide <Gmajor>.<Gminor><Gmod> qse.pdf
    • <Sminor> is omitted when 0
    • Gmod = a, b, c, ...; a jump from a to c means that I probably had a b but made further revisions before publishing it.
    • Gmajor.Gminor counting starts over when Streams (Smajor.Sminor) revs. This reflect the major changes in the product I've had to accommodate.
    • I did a more extensive edit of the guide when moving to the workspace-free version ("4.1.1 b"), so I went from 4.1 Lab Guide 1.0c to 1.1a.
  • I'm not claiming that any of this is necessary or even makes sense.

It would probably be better if I just had a single, version-controlled file for the lab guide (.docx) and treated the pdf as a build or release. I'm not sure if I should manage the installer as a project with every individual file managed as a version-controlled item, and the .zip again treated as a release package; or just manage the whole .zip (which in turn contains a shell script and a compressed tar ball) as a single asset. Now that I'm not including entire workspaces, the number of files to be managed (many of which do not change between releases) is much reduced.

I would like some guidance and help in this.

markheger commented

no need to change the lab