Skip to content

Need new type for How To style articles #647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vickitardif opened this issue Jul 17, 2015 · 29 comments
Closed

Need new type for How To style articles #647

vickitardif opened this issue Jul 17, 2015 · 29 comments
Labels
schema.org vocab General top level tag for issues on the vocabulary status:work expected We are likely to, or would like to, or probably should try, ... to do something in this area.

Comments

@vickitardif
Copy link
Contributor

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.

@vickitardif vickitardif added schema.org vocab General top level tag for issues on the vocabulary status:work expected We are likely to, or would like to, or probably should try, ... to do something in this area. labels Jul 17, 2015
@chaals
Copy link
Contributor

chaals commented Jul 20, 2015

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

@danbri
Copy link
Contributor

danbri commented Jul 28, 2015

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
Copy link
Contributor

danbri commented Jul 28, 2015

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
Copy link
Contributor

danbri commented Jul 28, 2015

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

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

@chaals
Copy link
Contributor

chaals commented Jul 28, 2015

@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
Copy link
Contributor

danbri commented Jul 28, 2015

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
Copy link

You should check out DITA task topics.

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

@danbri
Copy link
Contributor

danbri commented Jul 28, 2015

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
Copy link

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
Copy link

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
Copy link

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

@danbri
Copy link
Contributor

danbri commented Dec 13, 2015

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
Copy link
Contributor

chaals commented Dec 13, 2015

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

@vickitardif
Copy link
Contributor Author

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

@dragonghy
Copy link

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
Copy link
Contributor

danbri commented Mar 31, 2016

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
Copy link
Contributor

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
Copy link
Contributor

danbri commented Mar 31, 2016

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
Copy link

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
Copy link
Contributor

@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
Copy link
Contributor

danbri commented Apr 1, 2016

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

@Dataliberate
Copy link
Contributor

Dataliberate commented Apr 1, 2016

InstructionSet sounds a good compromise.

@vickitardif
Copy link
Contributor Author

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

@danbri
Copy link
Contributor

danbri commented Apr 25, 2016

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

@socceroos
Copy link

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
Copy link
Contributor

danbri commented Jun 1, 2017

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

@earljwagner
Copy link
Contributor

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
Copy link
Contributor

danbri commented Jun 15, 2017

@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.

@vickitardif
Copy link
Contributor Author

We have HowTo now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
schema.org vocab General top level tag for issues on the vocabulary status:work expected We are likely to, or would like to, or probably should try, ... to do something in this area.
Projects
None yet
Development

No branches or pull requests

10 participants