Help

Have a look and consider reaching out if you still need help.

How do you suggest I assess progress?

  • Projects
  • Participation
  • Papers

Why not just use a wiki?

You will note some of the SOIL standard draws on best practices established on Wikipedia and other Wiki platforms—particularly notes and references.

Wikis have proven valuable in capturing collectively maintained information, but they are fundamentally dependent on an Internet connection and cannot be encapsulated and delivered as an app.

Wikis also have several competing formats and no standard nearly as prevalent as Git.

Wikis cannot allow interactive content to be embedded within them because the technology behind wikis predates many of the advances in component-based web development and the offline-first movement.

Wikis are usually focused on containing knowledge but not particularly for creating skill-based learning material which SOIL seeks to cover as well as base knowledge.

Most wikis do not allow content to be considered modularly. This becomes prohibitive when considering separate content released under different license terms.

Why don't SOIL modules have versions?

The latest updated version is usually the best when working with educational content. When a specific version must exist while a new version of that content also exists then a new module should be created for the new version indicating in the 🏠 home URL something distinct from the original (ex: some-v2).

Why not just use the web itself?

While it is true that the 🏠 home URL refers to a rendered web version of a SOIL module it is possible to render any SOIL module in an entirely different way by accessing the git source itself. This is a key distinction from any simple web page.

In fact, light-weight SOIL browsers can be created that understanding nothing more than BaseML, which is essentially plain text and raster images. Such a light-weight browser need not even understand HTML at all nor even depend on the Web using the internet address of source files only.

This is the very reason interactive content must be secondary for all SOIL modules. It enables educational browsers to be created that do not require the bandwidth and hardware of modern evergreen web browsers. This is what is meant by the principle of progressive web applications that adapt to what is available to the user. We are simply applying the same principle in a macro way to educational content.

💬 A significant portion of the world still does not have more than basic Internet access and with devices that do not have the power to efficiently render SVG images or basic web animation. In such places, SOIL modules can be delivered as zipped content files and distributed without even having an Internet connection.

Can I use VuePress for a SOIL module?

Absolutely! It is the preferred method currently.

Consider not using the Algoia document search option only because it adds a dependency on the Internet that might thwart the offline-first SOIL focus. The basic search with VuePress includes all BaseML headings that are allowed. Make sure your important search terms are contained in one of these.

What about KaTex, LaTeX, and MathML?

Simply put, don't use them.

A good amount of the world's educational content depends on math equations and scientific notation. The publishing world has long standardized on LaTeX for rendering these to print. MathML and others add this to the web but in all cases a simple raster image will suffice.

One primary goal of SOIL is to create content that can be spoken with speech synthesis and natural language processors. Equations simply cannot easily be spoken in notation form.

Therefore, creation of a raster image with alternative text that can be voiced is required. This maintains the priority on simplified learning content available to anyone, including the visually impaired, and allows the development of learning tools that can apply natural language processing and input.

Use of raster images also simplifies the requirements of the SOIL module content renderer.

Where can I get copies of the logos?

These are all free to use but should not be used on anything that is not compliant with the current SOIL standard.

Why is video content secondary?

A picture is worth a thousand words so a video must be worth millions, right? Unfortunately overuse of video can distract from the content and relying on it eliminates the sight-impaired from using content that could otherwise have been written and voice-enabled.

That said, video is often required or a viable secondary supplement. Just remember not to depend on it unless you must.

How much content should I put into a single SOIL module?

That depends entirely on the content. SOIL modularity allows modules to be made up of other modules so they can be as large or small as needed.

That said, the size of the git repository and type of rendering engine will enter as practical considerations. For example, when using VuePress and hosting on Netlify you might prefer one large repo containing several composite modules to enable all the content to be included into a single progressive web app that can be downloaded to most mobile home screens. This has the advantage of indexing all the headers and making them instantly available for search. Learners need only install a single app rather than several.

Or, you could create an architecture of many SOIL modules being registered on a central web site that does its own indexing of BaseML Macro-Semantic data.

Which style guide should I follow for my writing?

The SOIL style guide is strongly recommended but not required.

The problem with all of the other style manuals is that none of them take into account modern digital media with hyperlinks and conversational interface compatibility.

We have an opportunity with SOIL to arrive at a standard for digital learning content that can take thinks like the following into account:

Last Updated: 10/22/2018, 12:23:13 AM