Comments:

• InstructionSet - suggest the following...
  • Rename cost to estimatedCost (possibly make it a subtype of amount)
  • Add CreativeWork to expected Types - then there could be a single instructions document or a list of them (note typo in description - should be CreativeWork not CreativeType)
  • Rename yield - a word with many meanings. Perhaps we could reuse outcome with a bit of rewording of the description.
• InstructionSupply - suggest the following...
  • Rename to InstructionSupplyItem
  • Make it a subtype of ListItem, this would help with ordering etc.
  • Use estimatedCost (see above) instead of amount

@Dataliberate thanks for the comments! 3 things to clarify:

(InstructionSet) Add CreativeWork to expected Types - then there could be a single instructions document or a list of them (note typo in description - should be CreativeWork not CreativeType)

Where the "expected types" should be added? In the instructions field description or the class description?

(InstructionSupply) Make it a subtype of ListItem

Is it possible to make it a subclass of both ListItem and CreativeWork? If not, can I specify item field to be a CreativeWork instead of Thing?

(InstructionSupply) Use estimatedCost (see above) instead of amount

Instead of estimatedCost, would estimatedAmount be more appropriate. It's something like 2 dozens, 1 ounce.

Updated code and http://schemaorg-127321.appspot.com/ per @Dataliberate's comment except the bullets mentioned above.

Sorry for my lack of clarity.
I was indicating that the range for instructions should include ItemList and CreativeWork. The description could then say that the instructions could be in a CreativeWork (document, video, etc) or in an ordered list of individual steps.

This 2nd look has made me think you are missing something from this proposal that possibly could work better as:

Thing > CreativeWork > InstructionSet - A set of instructions that teaches how to do something.
       * estimatedCost [Number,Text] Estimated cost of item(s).
       * instructions [ItemList, CreativeWork, Text] A list of instructions either in a single 
         form [Document, video, etc.] or an ordered list of InstructionStep items.
       * outcome [QuantitativeValue, Text] Outcome from the instructions. For example, 20 cakes, a meal for 10 people.
       * supplies [ItemList, Text] A related list of supplies. The list should contain items of type
         InstructionSupply.

Thing > Intangible > ListItem>InstructionStep - A step in a set of instructions
        * instructionDetail [Text, CreativeWork] 
        * supplies [ItemList, Text] A related list of supplies. The list should contain items of type
          InstructionSupply.

Thing > Intangible > ListItem>InstructionSupply - Supply item for an instruction set.
       * estimatedCost [Number,Text] Estimated cost of item(s).
       * supplyItem [Product] RequiredProduct.
       * requiredQuantity [Number,QuantitativeValue] Required quantity of item

Taking this approach would make it simple to order individual instructions and if needed the supply items the instructions. Also as well as listing all supplies relevant to the instruction step you would have the option to link a subset to individual steps in the process.

Some examples would be good to clarify things.

Let us find some name other than InstructionSet. Will be confusing for
folks in CS.

estimatedCost should use PriceSpecification instead of Number,Text so we can encourage correctly specifying currency and can support ranges.

I was tempted to suggest it myself - was thinking that MonetaryAmount (from
PR #965 #965) would be more
appropriate if it is accepted.

+1 for @rvguha 's point regarding naming: InstructionSet sounds like computing jargon

how about things like (I am really bad at naming)

• HowToInstructions
• HowToMethod
• Method
• DIYInstructions
• DIYInstructionSet
• DIYTutorials
  -TutorialInstructions

Updated code and http://schemaorg-127321.appspot.com/ per @Dataliberate and @vholland's comment.

@Dataliberate I think having an InstructionStep makes it more clear. I had to rename some of the fields though since I wanted to have different description for them (e.g. estimatedCost v.s. estimatedSupplyCost). It seems like description overwrites each other for fields with the same name even if they are in different classes.

I understand your desire to have separate descriptions for a property dependant on which type (class) it is being used. Unfortunately a property only has one definition which is reused wherever it is displayed on the Schema.org site. There have been, yet to be acted upon, thoughts on how Type specific notes could be added to descriptions but there is nothing there yet.

From your words I believe you agree that the property named estimatedCost would work for both InstructionSupply and InstructionSet. It is just the description issue that is causing you to suggest a second property. That is why I simplified the description in my suggestion to Estimated cost of item(s).

I believe that such a generic description, coupled with the description of the Type it is being used with and associated examples, will give sufficient guidance to a user. Also I would see potential wider reuse of such a property, in which case a generic description is helpful.

I recommend that estimatedCost with a simple generic description is used for both InstructionSupply and InstructionSet.

As to naming, taking in to account that once established these Types could be used not only for DIY projects but also potentially for industrial processes, or scientific projects, recipes, etc., I think the most appropriate name root suggested so far is Method.

~Richard

Agreed that a simple description is a best fit for a generic field name. Though a more class-specific description usually helps, it's fine to me having a generic class field for estimatedCost. Will update.

@danbri @rvguha @vholland would love to have you thoughts on the naming. Does Method (combined with MethodStep, MethodSupply) work for everyone?

I quite liked idea of something based on "HowTo", ... it keeps things informal and hints at the parallel with Recipe. "Method" can mean many things in many settings (e.g. methods in OO programming)

Looking at the example here, it is basically a Recipe ("How to Make Healthy and Crunchy Granola"), for which we have already got extensive and widely used vocabulary.

In fact one of the problems with Recipe is that people have been using it for non-edible tasks because we had nothing else. I suggest we move to a less foodie example and double-check that vocabulary is aligned as much as possible with Recipe (as well as with whatever we're doing around Courses...).

Added two new examples into http://schemaorg-127321.appspot.com/InstructionSet

One is for how to replace iPhone screen (skill).
The other is for how to make a hand-dotted tumblers.

The only thing I found missing was a difficulty level, which seems to be a common flag for a lot of diy websites.

@dragonghy thanks. How does this design relate to @chaals point in #617 that it ought to aim at being a superset of the current Recipe design. Are we close to that?

@danbri The link (#617) may not be what you wanted to send.

Indeed, sorry! #647

(I scrolled to the top of the page to find the number, scrolled back down, and ... well, my short term memory isn't what I remember it being...)

@danbri It does look like a good idea to me. The only issue is that some recipe fields may need to be renamed (to use the parent's field) or be kept in parallel with a similar field in parent class, including

• recipeIngredient -> supplies (inherited from parent)
• recipeInstructions -> instructions (inherited from parent)
• recipeYield -> yield or outcome (inherited from parent)
• (probably) recipeCategory -> category (for future compatibility)
• (probably) cookTime -> makeTime or something else indicating it's totalTime - prepTime (for future compatibility)

Please let me know your take on this. I'm more than happy to update the Recipe class if this people are cool changing the field names or keeping both recipe-specific and parent field names.

A decent amount of Recipe markup exists already. Can we make the recipe-specific properties subproperties of the new ones rather than renaming?

Yes, subproperty is the right mechanism here

It's the first time that I heard about subproperty. Is it something like the resultReview property in http://schema.org/ReviewAction? Basically, is "sub property" a property that's described as a sub-property of another property, without any strict inheritance?

I mean, it works for me. Just not sure if this is a concept that's widely adopted.

Yes, it's a piece of schema.org's infrastructure. Sometimes we have pairs of properties where one of them is more specific, and says the same thing as the general one plus some other stuff. By declaring a subproperty relationship it gives a bit more built-in navigation within the site, as well as helps consumers understand how different structures relate.

For example, if we said that 'recipeYield' was a subproperty of the more general 'yield' property, we should make sure that 'yield' expects the same kinds of values, so that "X recipeYield Y" could be turned into "X yield Y" automatically.

Gonna drop this since I am not working on this anymore.

Thanks for your efforts, @dragonghy

I will reopen this as there seems to be broader (if slow moving) interest...

Creating a new InstructionSet class would make TechArticle almost redundant, according to the description this is what its for.
Thing > CreativeWork > Article > TechArticel

A technical article - Example: How-to (task) topics, step-by-step, procedural troubleshooting, specifications, etc.

You could simply add an instructions property to this.

• dependencies | Text | Prerequisites needed to fulfill steps in article.
• proficiencyLevel | Text | Proficiency needed for this content; expected values: 'Beginner', 'Expert'.
• instructions | ItemList or Text | A step or instruction involved

and this means the APIReferance class can be used for platform specific tutorial by populating the targetPlatform property.

@danbri I would like to continue pushing this forward. Looking over the threads I agree with @tarranjones that the ability to write how to's, step by step, etc pretty much exists in Tech Article. My addition to the thread is add Product to dependencies.

@my-def-diesel As the "dependencies" Property is plural I would expect the itemProp attribute to only be declared once, meaning an Expected Type of "Product" would only allow for a single dependancy while "Text" would allow for multiple but less informative dependencies".

For the "dependancies" value to contain multiple dependancies then the Expected Types are limited "Text", "URL", "ItemList" etc.

If the "dependencies" Property were to become singular and be renamed "dependancy" or "dependsOn" then the itemProp attribute could be declared multiple times which would increase the benefit of having "Product" as an Expected Type.

• dependency | Text or Product | Prerequisite needed to fulfil steps in article.

@my-def-diesel I think giving "dependency" an Expected Type of "Product" would be too specific, "Thing" would be more flexible and beneficial.

• dependency | Thing | Prerequisite needed to fulfil steps in article.

I have to say I like @tarranjones's suggestion:
instructions | ItemList or Text | A step or instruction involved.

TechArticle's description mentions "How-to" and "step-by-step" but offers nothing to be able to express a structured set of steps yet for which ItemList contains all the necessary building blocks.

1+1=2 yes, no?

http://webschemas.org/recipeInstructions also has ItemList of Text, and could be a subproperty of a more generic 'instructions'.

Nice @danbri, I guess that 1+1=3 then.

closing as I am not working on this.