Need new type for How To style articles

[vholland]

This has come up a few times, most recently on public-schemaorg@w3.org. There should be a type for describing instructions outside of recipes. There are a lot of how-to videos and websites that would benefit from the ability to mark up the steps.

[chaals]

My preference would be to generalise recipes, but I could live with making something of which recipe is a subclass...

[danbri]

An intermediate case: recipes for non-human animals, e.g. DIY dog treats. I would include food recipes for all consumers (including dogs) within Recipe proper, and suggest a clean break and parallel type for 'how to' situations that don't share things like 'yield', 'nutrition', 'cookTime' etc. "Recipe for" can be super metaphorical and applied to almost anything. It would be good to keep Recipe focussed on food and nutrition, so we can improve its relationship to health/medical and product nutrition labelling (gs1) situations.

[danbri]

We could (and should) collect some examples of non-food instructions that might be usefully marked up.

For example https://github.com/jarkman/shonkbot has an ordered list of instructions for making an arduino-based robot, including the several products you'll need for doing so. Please suggest others!

[danbri]

More use cases, fairly close to foodie recipes but not conventionally considered food:

• cover medicines (cough syrup)
• facial scrub
• homemade floor cleaner

[chaals]

@danbri said

It would be good to keep Recipe focussed on food and nutrition, so we can improve its relationship to health/medical and product nutrition labelling (gs1) situations.

I disagree, but I can live with it. Let's call it a decision and be done.

What about "instructions"?

• How to plug in your devices
• How to troubleshoot your printer / heating / fancy cooking gadget
• How to make furniture (now that you buy it in pieces)

What about the things you need to do and have to apply for a visa, or to get a driver's licence?

[danbri]

Thanks re decision. I'm not "over my dead body" about this but sometimes a coin needs flipping decisively one way or the other to unblock things. Let's work through some usecases and see where that takes us, paying particular attention to which clusters of properties are needed for which scenarios.

For your howto instructions (devices, troubleshooting, furniture assembly), visa application and driver's license ... how important are (a) sequence / order (b) pre-requisites / ingredients? Are the structures more like simple lists (maybe with optional vs required), or are they getting closer to C++ makefiles with complex tree structures? For the visa application case I can see lots of conditional branching, which is scary: "are you married to a national? are you living here currently? are you or have you ever been a member of the xyz party?" ... The others seem easier to attempt with simple list-like structures, perhaps with alternative options for the pre-requisites ('sugar or honey'...).

Related vocabulary: http://schema.org/Question and http://schema.org/Answer ... which brings us back to the C++/makefile tarpit, the closer we get to technology. The stackexchange (stackoverflow etc.) sites are currently using Question and Answer to mark up their stuff, e.g. view-source:http://serverfault.com/questions/301123/connect-over-wifi-to-sql-server-from-another-computer

Do you have a 'recipe' (howto, instruction etc.) for "Connect over WiFi to SQL Server from another computer"?

That particular site doesn't give explicit list ordering to the answers, but you can see list-like patterns in the prose for this (randomly picked) example:

<div itemscope itemtype="http://schema.org/Question">
  <link itemprop="image" href="//cdn.sstatic.net/serverfault/img/apple-touch-icon.png?v=6c3100d858bb">
  <h1 itemprop="name"><a href="/questions/301123/connect-over-wifi-to-sql-server-from-another-computer" class="question-hyperlink">Connect over WiFi to SQL Server from another computer</a></h1>
  <span itemprop="upvoteCount" class="vote-count-post ">1</span>
  <div class="post-text" itemprop="text">
  <p>I tried to connect over WiFi to SQL Server with SQL Server Management Studio from another computer, but it failed.</p>
  ...
 <span style="display:none;" itemprop="answerCount">4</span>
</div>

+ several answers, e.g.

<div id="answer-301619" class="answer" data-answerid="301619"  itemscope itemtype="http://schema.org/Answer">
  <span itemprop="upvoteCount" class="vote-count-post ">1</span>
  <div class="post-text" itemprop="text">
  <p>First, the way to address a specific SQL server instance is: SERVERNAME\INSTANCENAME</p>
  <p>So, first step is to see if you can resolve SERVERNAME (use ping or change it for an IP address).</p>
  <p>The second step is to see if the specific instance exists. Typically, the first instance of MSSQL server is using the default instabnce name (. or MSSQLSERVER). If that's the case, you can omit the instance name in your connection string and keep the server name only.</p>
...
</div>

Given that the Web is awash with ordered listicles there might be a trend towards sites making such structure more explicit. I haven't dug too deeply but https://en.wikipedia.org/wiki/Listicle#Collaborative has some examples.

[duckAsteroid]

You should check out DITA task topics.

Note: I think this stuff goes back even further to similar looking structures in SGML.

[danbri]

Thanks @duckAsteroid - very interesting! They get around the formally-structured-vs-informal by having specs for both. We do much the same in schema.org in a few places already too.

[tomwaddington]

I run a site with recipes and tutorial content - I'd love to see something more generic than recipes, and more specific than articles for the content.

I could imagine ItemList > InstructionList, with a listitem containing step data, images/video etc.

[dragonghy]

It's awesome to see this discussion. We are running into the problem to markup DIY/tutorial/how-to contents from partners website and would love to push this issue to be resolved on schema.org.

How people do it today

• SnapGuide is one of more favorite DIY (including recipe) website today. Check this how-to step-by-step instruction out.
• some websites offer DIY contents as videos, check this out.

Why another schema is necessary

No DIY schema? okay, people use recipe schema to mark up DIY contents. The parsed result looks bad btw: ingredients: 1 Cup Washing Soda (cleaner)

In addition to the naming issue (recipeInstructions, recipeIngredient, recipeYield, cookTime), there are couple more asks for DIY markup:

• supplies, which is similar but not necessarily the ingredients. It's richer and may include product information since a lot of DIY content providers mean to sell the supplies in the end.
• instructions needs to be richer. It should include fields for images, videos and additional context (tools needed) if necessary.

Draft schema

We have no experience to design the markup schema before. Below is the drafted schema that we proposed and are using to collaborate with partners today. It would be great if it helps outline the DIY/tutorial schema. We appreciate any feedbacks you have. (e.g. we are not sure for the usage for itemList and QuantitativeValue. )

Basically we hope to add two new types: Tutorial and TutorialSupply

Tutorial (inherited from CreativeWork)

Property	Type	Description
name	Text	Required. (inherited from Thing)
description	Text	Required. (inherited from Thing)
timeRequired	Duration	(inherited from Thing)
image	URL or ImageObject	Required. (inherited from Thing)
url	URL	Used for feed. (inherited from Thing)
author	Person or Organization	(inherited from CreativeWork)
video	VideoObject	(inherited from CreativeWork)
tutorialCost	Text or QuantitativeValue	Estimated cost to complete.
tutorialSupplies	ItemList	List of supplies. (Text or TutorialSupply*)
tutorialInstructions	ItemList	List of instructions. (Text or CreativeWork)
tutorialYield	Text or QuantitativeValue	Tutorial yield. For example, 10 people, 20 cakes, etc.

TutorialSupply

Property	Type	Description
amount	Text, Number or QuantitativeValue	Amount of the supply item.
product	Text or Product	Name or product object for the supply.

Sample:

HTML without markup

<div> 
  <span>How to Make Healthy and Crunchy Granola</span>
  <p>Yummy and vegan-friendly granola.</p>
  by <span>Beate Olav</span>
  <h1>Step one</h1>
  <div>
    <img src="//d1alt1wkdk73qo.cloudfront.net/images/guide/344b3648d14541698ae60bebbb3104d3/640x960.jpg" width="640" height="960">
    <p>Ingredients: porridge oats, flax seeds, pumpkin seeds, almonds, wholefood/eco-friendly maple sirup, ground cardamom</p>
  </div>

  <h1>Step two</h1>
  <div>
    <img src="//d1alt1wkdk73qo.cloudfront.net/images/guide/ce22ef0f89f64c62978d31e00fae27b1/640x960.jpg" width="640" height="960">
    <p>Mix dry and wet Ingredients in a bowl</p>
  </div>

  <h1>Ingredients</h1>
  <ul>
    <li>1 Cup Porridge oats</li>
    <li>½ Cups Pumpkin seeds</li>
  </ul>
</div>

Microdata

<div itemscope itemtype="http://schema.org/Tutorial"> 
  <span itemprop=”name”>How to Make Healthy and Crunchy Granola</span>
  <p itemprop=”description”>Yummy and vegan-friendly granola.</p>
  by <span itemprop=”author”>Beate Olav</span>
  <h1>Step one</h1>
  <div itemprop=”tutorialInstructions” itemscope>
    <div itemprop=”itemListElement” itemscope itemtype="http://schema.org/CreativeWork">
      <img itemprop=”image” src="//d1alt1wkdk73qo.cloudfront.net/images/guide/344b3648d14541698ae60bebbb3104d3/640x960.jpg" width="640" height="960">
      <p itemprop=”description”>Ingredients: porridge oats, flax seeds, pumpkin seeds, almonds, wholefood/eco-friendly maple sirup, ground cardamom</p>
    </div>

    <h1>Step two</h1>
    <div itemprop=”itemListElement” itemscope itemtype="http://schema.org/CreativeWork">
      <img itemprop=”image” src="//d1alt1wkdk73qo.cloudfront.net/images/guide/ce22ef0f89f64c62978d31e00fae27b1/640x960.jpg" width="640" height="960">
      <p itemprop=”description”>Mix dry and wet Ingredients in a bowl</p>
    </div>
  </div>

  <h1>Ingredients</h1>
  <ul itemprop=”tutorialSupplies” itemscope>
    <li itemprop=”itemListElement” itemscope itemtype="http://schema.org/TutorialSupply">
      <span itemprop=”amount”>1 Cup</span>
      <span itemprop=”product”>Porridge oats</span>
    </li>
    <li itemprop=”itemListElement” itemscope itemtype="http://schema.org/TutorialSupply">
      <span itemprop=”amount”>½ Cups</span>
      <span itemprop=”product”>Pumpkin seeds</span>
    </li>
  </ul>
</div>

JSON-LD (which can be used in partner feeds)

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": “Tutorial”,
  "name": "How to Make Healthy and Crunchy Granola",
  "description": "Yummy and vegan-friendly granola.",
  "author": "Beate Olav",
  "tutorialInstructions: {
    "@type": "ItemList",
    "itemListElement": [
      {
        "@type": "CreativeWork",
        "image": "//d1alt1wkdk73qo.cloudfront.net/images/guide/344b3648d14541698ae60bebbb3104d3/640x960.jpg",
        “description”: “Ingredients: porridge oats, flax seeds, pumpkin seeds, almonds, wholefood/eco-friendly maple sirup, ground cardamom”
      },
      {
        "@type": "CreativeWork",
        "image": "//d1alt1wkdk73qo.cloudfront.net/images/guide/ce22ef0f89f64c62978d31e00fae27b1/640x960.jpg",
        “description”: “Mix dry and wet Ingredients in a bowl”
      }
    ]
  },
  "tutorialSupplies: {
    "@type": "ItemList",
    "itemListElement": [
      {
        "@type": "TutorialSupply",
        "amount": "1 Cup",
        “product”: “Porridge oats”
      },
      {
        "@type": "TutorialSupply",
        "amount": "½ Cups",
        “product”: “Pumpkin seeds”
      }
    ]
  }
}
</script>

@danbri

[dragonghy]

@danbri any chance could I get some feedback for this?

[danbri]

I'd like to move ahead in this direction. Does anyone here think that we shouldn't?

/cc @ajax-als @chaals @mfhepp @pmika @scor @shankarnat @tmarshbing @vholland @rvguha

[chaals]

On Sun, 13 Dec 2015 14:38:22 +0300, Dan Brickley
notifications@github.com wrote:

I'd like to move ahead in this direction. Does anyone here think that we
shouldn't?
agree we should

Charles McCathie Nevile - web standards - CTO Office, Yandex
chaals@yandex-team.ru - - - Find more at http://yandex.com

[vholland]

Small nit: The JSON-LD example needs "@list" to preserve the order of the instructions. Other than that, it looks good to me.

[dragonghy]

Sorry I haven't been an active github user apparently and missed the notification. :P

We have been actively pushing the how-to schemas with our partners and ~20 partners are using it today internationally. We have slightly updated the schemas since then. I'll update here as well.

@danbri @chaals @vholland: what's the best way to contribute to schemas.org? should I send out a pull request?

[danbri]

Thanks for the nudge - it would be good to progress this. Yes, please join the main Schema.org Community Group over at W3C - https://www.w3.org/community/csvw/ - and then submit a pull request here. The relevant files are all in the data/ directory in the repo. If anything is confusing please ping here.

[Dataliberate]

Basic structure looks fine. @vholland "@list" would not be needed if 'position', 'nextItem', 'previousItem' were used to indicate ordering in all serialisations.

The use of 'tutorial' in the naming may conflict in other domains "noun: a period of tuition given by a university or college tutor to an individual or very small group". Perhaps 'method' would be more appropriate "a particular procedure for accomplishing or approaching something, especially a systematic or established one"

[danbri]

re naming issues and overlaps - @philbarker could you take a look from an LRMI and courses perspective.

@dragonghy for context - we have also got some substantial efforts around markup for courses underway - see https://www.w3.org/community/schema-course-extend/

[dragonghy]

Thanks @danbri. I just signed up on w3c. It took me some time to understand how the community, the email thread and the example website come together. :)

We are very open to rename the schemas. "method" sounds good to me. We've also been thinking about "HowTo", "StepByStepTutorial" etc.

re: course seems very relevant. Very excited that there's already such a great discussion in the community. Here's my understanding after reading the pull request and the sample page.

The course object (at least for now) seems to be heavily designed for academia purpose but has less support for a DIY commercial provider (e.g. brit.co's DIY content, or a comprehensive step-by-step recipe. The current new fields in course don't seem to help at much (if any).

On the other hand, I do see a potential that some of the how-to tutorial fields may be useful to a course. Like supplies and yield (imagine it's an one-off sushi making course offered in San Francisco).

[philbarker]

@danbri On the naming & overlaps, in Higher Education at least, tutorial is already ambiguous. My experience is that the individual or small group tuition definition that @Dataliberate cites is now the exception (in practice at least, though perhaps not in people's minds), and that
" n. Something that provides special, often individual instruction, especially:
a. A book or class that provides instruction in a particular area.
b. Computers A program that provides instruction for the use of a system or of software."
(via http://www.thefreedictionary.com/tutorial) is more prevalent.

I don't think that calling this a tutorial causes any more confusion than already exists. Looking (briefly) at the scope of this discussion, it might be that "instruction set" would be less ambiguous and still encompass the sense of tutorial in the definition above.

[danbri]

In that case let's do it. We can try alternate wording once there is a draft implementation for wider review.

[Dataliberate]

InstructionSet sounds a good compromise.

[vholland]

Yes, the example either needs @list or to use nextItem or position.

[danbri]

Some related work here: https://datahub.io/dataset/human-activities-and-instructions (via @bquinn)

[socceroos]

Parallel to this proposal, are there plans to have a schema for WebGL based instructional items? Currently the 'video' schema is the closest thing but it seems improper to use.

An example: https://jig.space/view?jig=1o7L8e7d

It's both instructional and interactive. Video doesn't cover it, nor does this generic instructions proposal.

[danbri]

We ought to indicate when some Web content is available that gives deeper (textual, interactive or whatever) coverage of a recipe or HowTo...

[earljwagner]

The current proposal offers some options for other web media for instructions:

• To illustrate directions (i.e. actions) in individual steps, a HowToDirection can have before/during/afterMedia properties set.
• The "steps" property of a HowTo can be any CreativeWork, not just text.
• At the most general level, a HowTo inherits the "associatedMedia" property for CreativeWork.

[danbri]

@earljwagner yes, another pattern is also just that the page with the HowTo content also has an embedded MediaObject (in which case presumably best practice would be for the markup to make the association explicit rather than implicit, eg. with associatedMedia or the more granular options you mention). If the link isn't made it is probably still a fairly safe bet that that video is about the howto'd task.

[vholland]

We have HowTo now.