About

This SOIL module and GitHub repository has three purposes:

  1. to informally explain SOIL modules
  2. to give you something to copy to get you started
  3. to explain the steps to create your own SOIL modules.

😁 If this seems too complicated and you wish to get started creating content with less technical hassle consider reaching out to your local Instructional Technologist to help you setup everything so you can just edit and save your content in plain BaseML, a web content language created by a writer (not a scientist). You can see this page as BaseML if you want to see how easy it is to write.

Prerequisites

Before attempting to create your own SOIL modules you should first master the following:

You should also be generally familiar with the following:

You can combine About, Index, Main, and FAQ for small modules.

About

Index

The index is the combination of the traditional table of contents, normally at the front of the text, and the index of terms, normally at the end.

The reason for this combination is most renderers will allow searching by keyword so the traditional keyword-based index is no longer needed.

Entry into the data is also less traditional allowing directly jumps all around. This leaves the content found in a traditional table of contents someplace in either the about page or the index. Learners become familiar with the concept of the index and know to look at it for a quick visual summary of everything. For searching they use the rendered search box.

Index is usually in the /index/ directory and almost always has a navigational menu entry.

There are no constraints on the appearance or form of the index other than those imposed by BaseML. For example, lists must be only one level. A traditional outline can be done by combining headers and lists.

Rather than provide a complicated table of contents the about page should refer to other content (linked locally or externally) in a way that can be conversationally summarized. This makes it easy for learners to follow the content or find their way.

💬 Note that when using a recommended tool like VuePress to generate a SOIL module the organization of the content is provided automatically in the form of sidebars and navigation menus but this should never be depended upon.

Main

Main is rarely called main. In this module it is Learn. It might be spread out into different directories beside just one. This is where you should put the meat of the module content.

If you want to organize your content into chapter or projects you might make a module with folder and README.md file for each chapter.

💬 By the way, there is nothing wrong with putting all the content into a single main file if you like and leaving out the about and index.

This organization is up to you and closely models the decision making of software developers as they decide what should be a module or library and what should go into main.

💬 In the software world the relation between the index and main content is similar to the header (.h) files in C and the compiled libraries themselves (.a, .so, .dll).

Includes

Any content that is either locally or externally linked from this module is logically considered a part of it. If that link is also a prerequisite then it will be flagged as such by link checkers. If the content pointed to by the links contains a SOIL Fence it will be considered as being composed into the current module.

This approach prevents the need for an additional package dependency configuration file (i.e. package.json). Read more about dependencies in the standard.

Scope

Remember that adding a SOIL fence essentially exports that content as a public module for inclusion through linking by others.

Read more about scope in the standard.

Bottom line: only put SOIL fences in content that you want others to link to.

SOIL Fence

The SOIL fence meta data can appear anywhere in the document but is generally the last thing. It should become obvious to those working with SOIL modules regularly what it means.

You likely do not need all the properties included. Delete those you don't need. The top three (home, source, and license) are required. These are explained in the standard.

🏠 vuepress.soilsrc.org/intro
💎 soilsrc/vuepress
📃 by-sa/4.0
✉️ info@soilsrc.org
🔰 >=13
⏱️ 15m
✅ soilsrc.org/intro
🌐 en-US
Last Updated: 10/19/2018, 8:21:48 PM