Feature Proposal: Katacoda Foswiki tutorial

Motivation

I have used Foswiki and its predecessor since 2002. I am user, not a developer. Over the years I have learned to look under the hood when the documentation failed me (Or when I failed to understand the documentation). I have updated some plugins and written a few. And I have many times looked back on my travels and thought: "Oh, is that what this is meant to do?"

I have often thought that a book, presenting the features of Foswiki would be a great idea. I and many others, looking at the Feature proposals listed. I have embarked at writing such a book. And that is in a half finished state because I cannot interest a publisher.

Interest in wikis in general is waning and Foswiki is no exception. I have read the discussion around a more interesting and maintainable implementation of Foswiki core using an better, object oriented architecture. I even tried to contribute, but my health, my ignorance of Moo and the abysmal debugging features in a perl Moo environment got the better of me and I gave up. On reflection, I don't believe that the interest in Foswiki can be revived by a better core.

What attracts me to Foswiki is the functionality available. If that could be presented in a way that gave a potential user a leg up across the breadth of the application, I believe people would less likely to give up an hour after the installation. Because, lets face it, once you have downloaded the application, all you have is a text editor and some formatting. Github provides that service with better editing and formatting. And there are few obvious distinguishing Foswiki features that would compel me to struggle on.

For me the attraction of Foswiki has been the ability to build applications. But I did not discover/understand the wiki workbench until 2015! And despite all the suggestions that it would be a good idea, I have not found a single, out-of-the-box working application shipped with Foswiki. I believe that Foswiki requires a more coherent introduction to its capabilities than is available on the Foswiki web site. Until recently I was convinced that a book would be the best vehicle to present this introduction.

And then I came across Katacoda. Katacoda supports an environment where text, examples and experimentation can be easily implemented. I have spent some gloomy, smokey days experimenting and have created an introduction to Foswiki that presents Webs, Macros, Templates, Forms and Extensions in a working environment. You can see that here. You will need to register or you can log in with a Github, LinkedIn, Twitter or Google. Source for these courses is on github.

My proposal
is to extend this tutorial with additional scenarios about building applications. And maintain them as a Contrib. I have outlines for the following scenarios:

• Part Two - Wiki Applications
  • A Note Pad Application
  • The Wiki Workbench
  • More Wiki Workbench Functions
  • Note Pad Application Version Two
• Part Three - Wiki Applications In Action
  • Upgrading The Task Management System
  • Preening The Task Management System
  • The Book App
  • The Mail Archive App

So where to from here?

Description and Documentation

Katacoda is a fairly simple tool to provide on-line course material in an IT environment. It provides a panel for the instruction, next to a panel with a bash shell or browser. The narrative can contain shell commands that can be executed in the shell with a single mouse click. It also provides a mechanisn that copies prepared text to the paste buffer, for pasting in other locations. The narrative and commands are written in markdown.

The Katacoda documentation is sparse, but adequate if you are prepared to experiment. A typical scenario is described with the index.json structure:

{
  "title": "Introduction to Foswiki",
  "description": "Foswiki features: Webs, Macros, Forms, Templates and Extensions",
  "difficulty": "beginner",
  "time": "20 minutes",
  "details": {
    "assets": {
      "host01": [
                { "file": "foswiki.conf", "target": "~/" },
                { "file": "SolutionExtensions.tgz", "target": "~/" },
                 { "file": "wait.sh", "target": "~/", "chmod": "+x" }
              ]
    },
    "steps": [{
      "title": "Extensions",
      "text": "step1.md",
      "answer": "step1-answer.md"
    },{
      "title": "Extensions (Cont...)",
      "text": "step2.md",
      "answer": "step2-answer.md"
    },{
      "title": "Extensions (Cont...)",
      "text": "step3.md",
      "answer": "step3-answer.md"
    },{
      "title": "Extensions (Cont...)",
      "text": "step4.md",
      "answer": "step4-answer.md"
    },{
      "title": "Extensions (Cont...)",
      "text": "step5.md"
    }],
    "intro": {
      "text": "intro.md",
      "courseData": "setup.sh",
      "code": "timer.sh",
      "credits": "Bram van Oosterhout"
    },
    "finish": {
      "text": "finish.md"
    }
  },
  "environment": {
    "uilayout": "terminal-iframe",
    "uimessage1": "\u001b[32mYour Interactive  Bash Ubuntu Terminal.\r\nRun your own commands here\u001b[m\r\n",
    "showdashboard": "1",
    "dashboards": [ {"name": "Foswiki", "port": "80", "host": "host01"} ]
  },
  "backend": {
    "imageid": "ubuntu"
  }
}

Examples

You can find the scenarios I have developed to date on github: https://github.com/BramVan-Oosterhout/katacoda-scenarios

And the results can be seen at: https://www.katacoda.com/bramvanoosterhout (You will need to login/register)

Impact

I believe that a collection of Katacoda scenarios is a superior vehicle to introduce the features of Foswiki to a new user. It will reduce the confrontation with the myriad of implementation details and at the same time demonstrates that Foswiki just works(tm). No struggles with configuration, copying examples from potentially out of date documentation or destroying your database with a poorly thought out plugin edit. The new user can just focus on what is possible and how to use Foswiki to address their business problem. I believe that will substantially reduce the barrier to entry.

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

To progress, I suggest to create a KatacodaContrib as a Foswiki repository. The repository could have a webhook to publish updates to the Katacoda.com/foswiki environment. The whole procedure is described on the Katacoda web site.

At the moment I install and configure Foswiki and the cpan dependencies from scratch at the start of each scenario. That takes a minute or two. I plan to start the next set of scenarios using TimothyLegge's docker implementation. That installs more and is faster when the scenario starts.

Something to look at: How long will Katacoda.com remain free now that O'Reilly has acquired Katacoda? I have written to O'Reilly and got this reply:

Subject: {S-3} RE: Katacoda [ ref:_00D412j7Ek._5002M1560Ji:ref ]    
Hi Bram,

Thanks for reaching out. Yes, at this time we have no means of shutting down the free services that Katacoda has on their site at this time. 

Tye L. | Customer Service
O'Reilly Media, Inc. | 707-827-7019 or 800-889-8969 | oreilly.com

So, they'd want to but can not. Katacoda does not respond to my queries.

As an alternative one could use Instruqt which provides a free service. But the implementation services a different audience, has a nicer user interface and a more complicated mechanism to put a tutorial like this together.

-- Contributors: BramVanOosterhout - 25 Feb 2020

Discussion

25 March 2020

I have finally got the docker-foswiki image fully functional in the Katacoda environment. I am ready to tackle more serious stuff.

Part 1, the introduction is now available on my github repository (BramVan-Oosterhout) as TutorialContrib. It's not packaged as a Foswiki contrib yet. That can wait until Part 2 is developed. But it is rendered as a course at https://www.katacoda.com/bramvanoosterhout-tutorial.

Part 2 will use the docker-foswiki install, which will start the scenarios a bit quicker. And it will cover the wiki workbench and build some very simple applications.

Being forced to stay home (Australia - Corona) may speed up progress. We live in interesting times. Stay well. Stay safe.

-- BramVanOosterhout - 25 Mar 2020

Interesting idea. Let me know if you need anything from the docker-foswiki side

-- TimothyLegge - 13 Apr 2020

Hi Tim,

Thanks for your interest. And your offer. Not sure whether my current problem is related to docker-foswiki. There is a description here: https://foswiki.org/Support/Question2043

I am struggling with Cross-Origin Resource Sharing. And I am not sure where things go wrong.Is it because I am using a container in a container? If you have any experience in this area, I could benefit from some hints.

Thanks again.

-- BramVanOosterhout - 14 Apr 2020

27 April 2020

Well, I have managed to set up tim's docker-foswiki operational in the Katacoda enviroment. I am writing the first scenario and all seems to work as expected. If things keep going this way, I may have Part 2 ready by July 2020.

If I start a Part 3, I will develop a docker image specific to the course. That will reduce the startup times. I find that i learn most when I trying to explain to others. But boy, it is slow.

Any suggestion or concerns, please let me know.

-- BramVanOosterhout - 27 Apr 2020

Hi All,

Its mid August now and I have updated the course at https://www.katacoda.com/bramvanoosterhout-tutorial with part 2. There are four scenarios:

• A simple application
  • Here you build a very simple application using the bare minimum of workbench components
• Some work bench internals
  • Explains the RenderSimpleTopicCreator step by step
• More work bench internals
  • explains the RenderTopicInstaller, RenderWikiTopicView and RenderTopicsOfType
• NotePadApp
  • Here you embellish the application you built previously. You will use Forms, Templates, Styling and Functions.

I will accept comments from anyone who cares. It's been a tough road. I had to built quite a bit of infrastructure to support the course in Katacoda. You will see a progression of approaches through the four scenarios. I expect there to be issues. And the examples for the last step in the NotePadApp scenario need addtional coordination.

I am taking off from the development until the end of September. I am happy to answer questions.

Have a look and let me know what you think.

-- BramVanOosterhout - 17 Aug 2020

22 November 2022 - Katacoda is no longer free.

Katacoda is now no longer free.

Hi Michael, Lynwood

I read through the minutes of the AGM. It's good to see that Foswiki tries to get more members. I fully agree that Foswiki's capabilities are superior to many. But they are hard to unlock.

I have worked on a Katacoda course, as well as a written course in an attempt to demystify the internals. And yet, I find new things, opportunities and quirks every time I make a move.

The Katacoda course stopped because I took on a task to upgrade 119 to 216. Although in principle straight forward, in practice there were a few grand surprises that took much time to get sorted out. They were mostly to do with Publish plugin

I like and use Publish plugin, but in the 119 to 216 transition it did my head in.

So then I decided to refactor Publish plugin. That is getting close, But I needed to install new hardware. The old one failed. That took quite a bit more time that I anticipated. I'm just in the process of finishing that.

Then it is back to Publish plugin and then to the Katacoda course.

All this just to illustrate that Foswiki, although powerful, is time consuming to get ones head around.

As to the ideas for advertising Foswiki:

1. I am very impressed with the docker image of Foswiki. It is the easiest way to get Foswiki up and going. So I suggest that, whatever else we undertake in the realm of demonstrations, use the docker image.
   • I hereby offer to write a blog post to demostrate the virtues.
2. I can also offer the text I have written relating to the use of Foswiki. It could be posted on the blog.
3. I recommend an environment like Katacoda as a vehicle to advertise Foswiki's capabilities. I will eventually get back to something like Katacoda. Katacoda is being usurped into O'Reilly and is not very usable any more. There are alternatives available. I have built a Foswiki application that creates the course and deploys it, via GitHub to Katacoda.
   • the tail end can be modified for another target.

I am happy to assist, but progress will be slow. there are many other things that take my time (Grand children, travel and so on). But I am happy to help.

To stay involved, is there a place where ideas and progress on your actions is visible?

All the best,

-- BramVanOosterhout - 22 Nov 2022

Commenting is disabled while not logged in