-
Notifications
You must be signed in to change notification settings - Fork 851
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
Comments
My preference would be to generalise recipes, but I could live with making something of which recipe is a subclass... |
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. |
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! |
More use cases, fairly close to foodie recipes but not conventionally considered food:
|
@danbri said
I disagree, but I can live with it. Let's call it a decision and be done. What about "instructions"?
What about the things you need to do and have to apply for a visa, or to get a driver's licence? |
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:
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. |
You should check out DITA task topics. Note: I think this stuff goes back even further to similar looking structures in SGML. |
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. |
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
Why another schema is necessary No DIY schema? okay, people use recipe schema to mark up DIY contents. The parsed result looks bad btw: In addition to the naming issue (
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 Basically we hope to add two new types: Tutorial (inherited from CreativeWork)
TutorialSupply
Sample: HTML without markup
Microdata
JSON-LD (which can be used in partner feeds)
|
@danbri any chance could I get some feedback for this? |
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 |
On Sun, 13 Dec 2015 14:38:22 +0300, Dan Brickley
Charles McCathie Nevile - web standards - CTO Office, Yandex |
Small nit: The JSON-LD example needs "@list" to preserve the order of the instructions. Other than that, it looks good to me. |
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? |
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. |
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" |
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/ |
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). |
@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 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. |
In that case let's do it. We can try alternate wording once there is a draft implementation for wider review. |
InstructionSet sounds a good compromise. |
Yes, the example either needs @list or to use nextItem or position. |
Some related work here: https://datahub.io/dataset/human-activities-and-instructions (via @bquinn) |
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. |
We ought to indicate when some Web content is available that gives deeper (textual, interactive or whatever) coverage of a recipe or HowTo... |
The current proposal offers some options for other web media for instructions:
|
@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. |
We have HowTo now. |
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.
The text was updated successfully, but these errors were encountered: