Re: Discussion topic: How to improve understanding and application of schema.org

I appreciate the responses.  Special thanks to Thad for facilitating and
getting this logged into Github.  Before I get into specific issues, I
first wanted to share some examples of documentation from other community
projects that are addressing broadly similar issues.

Open Standards for Data Guidebook

http://standards.theodi.org/


Why I like it"

* It’s visual (includes diagrams and infographics)

* It’s task-oriented (How to.., Getting Started, Lessons learned)

* It explains the broader context, so readers can understand how different
pieces fit together

* It explains rationales, provides guidance (When to…, When not to…)

* Different entry paths for different types of users (in their case: policy
specialists, domain experts, data publishers/consumers, orgs developing
standards)




Patterns from Open Data Institute Toolkit

http://www.opendataservices.coop/blog/2018/01/11/odi-open-standards-for-data.html


Why I like it:

* Good framework (Problem/Solution/Example)


Data on the Web Best Practices

https://www.w3.org/TR/dwbp/


Why I like it:

* Has a Best Practices Template (Why, Intended Outcome, Possible Approach
to Implementation, How to Test, Evidence, Benefits)

* Identifies key benefits by letters, which are associated with different
guidelines


Do you think any of these features can be used in schema.org documentation?


On Sun, Jun 17, 2018 at 9:11 AM, Anthony Moretti <anthony.moretti@gmail.com>
wrote:

> If it helps, I've tried to put together my suggestions from last week on
> making Schema easier. I realize a lot of people will disagree, and realize
> most of it is unlikely to go through. I do hope though that in the spirit
> of this thread it might help improve people's understanding of Schema, and
> who knows maybe even inform future tweaks. I welcome any feedback or
> questions.
>
> All types could ideally exist in pairs, following a naming pattern such as:
>
> *BaseType*
>
> *BaseTypeType*
>
>
> This pattern scales in the rare instances required:
>
> *BaseTypeTypeType*
>
> etc.
>
>
> The "some or all" test for subtyping should be strictly followed:
>
> If, and only if, *all* instances of one type are instances of another is
> it a subtype.
>
>
> Types without a clearly agreed meaning should be removed and their
> properties moved to the parent type. Time-wasting debates have been caused
> because of the lack of clear meaning of the following types:
>
> *CreativeWork*
> *Intangible*
> *Product*
>
>
> Combining the above points results in an arguably easier to learn, simpler
> to use, and (importantly) more scalable type hierarchy. A partial example
> of what it might look like (showing several subtypes of Place to
> demonstrate how it scales):
>
>
> *Thing*
> *    Action*
> *    Article*
> *    Book*
> *    Event*
> *    Game*
> *    Language*
> *    Movie*
> *    MusicRecording*
> *    Organization*
> *    Painting*
> *    Person*
> *    Place*
> *        Airport*
> *        Bridge*
> *        Hospital*
> *        Museum*
> *        Park*
> *    Reservation*
> *    ThingType*
> *        ActionType*
> *        ArticleType*
> *        BookType*
> *        EventType*
> *        GameType*
> *        LanguageType*
> *        MovieType*
> *        MusicRecordingType*
> *        OrganizationType*
> *        PaintingType*
> *        PersonType*
> *        PlaceType*
> *            AirportType*
> *            BridgeType*
> *            HospitalType*
> *            MuseumType*
> *            ParkType*
> *        ReservationType*
> *        TicketType*
> *        VehicleType*
> *        WebPageType*
> *        WebSiteType*
> *    Ticket*
> *    Vehicle*
> *    WebPage*
> *    WebSite*
>
>
> For greatest flexibility, and in the spirit of volcanoes-can-have-fax-numbers,
> a guideline similar to the rule of three
> <https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)> can
> then be applied:
>
> Whenever a property is used on more than two types move it to the parent
> type.
>
>
> Moving properties higher in the type hierarchy improves the flexibility of
> Schema, and might address some of the cross-domain concerns people have.
> Loading properties onto Thing is a good idea in my view, it achieves
> maximum reuse.
>
> A partial example of what it might look like:
>
> *Thing*
>     height
>     width
>     depth
>     weight
>     material
>     color
>
>     offers
>
>     predecessorOf
>     successorTo
>     variantOf
>
>         *Event*
>
>             endDate
>
>             startDate
>
>         *Person*
>
>             additionalName
>
>             familyName
>
>             givenName
>
> *        ThingType*
>             heightOfTypicalInstances
>             widthOfTypicalInstances
>             depthOfTypicalInstances
>             weightOfTypicalInstances
>             materialOfTypicalInstances
>             colorOfTypicalInstances
>             offersOfTypicalInstances
>             predecessorTypeOf
>             successorTypeTo
>             variantTypeOf
>
>
> The following are some other minor suggestions:
>
> When naming things, the underlying model combined with the naming
> convention above is enough to provide type-instance distinctions, so words
> like the following are ideally avoided in type names:
>
> Class
> Category
> Description
>
> Entity
>
> Individual
> Instance
> Model
>
> Object
>
> Occurence
> Specification
>
>
> (The exception is probably for subtypes of StructuredValue, where adding
> "Description" or "Specification" to the end of all type names might
> highlight that their instances have a different nature.)
>
> On the full hierarchy <https://schema.org/docs/full.html> page, instances
> of Enumeration (for example ActionStatusType, BoardingPolicyType, etc.)
> could be in a different text style (if they should be listed on the page at
> all). Also, to follow the pattern of the example type hierarchy above and
> to give organization, a subtype of Enumeration, TypeEnumeration, could be
> created:
>
> *Enumeration*
> *    TypeEnumeration*
>
>
> For consistency's sake, the same could be done for structured values:
>
> *StructuredValue*
> *    TypeStructuredValue*
>
>
> Also on the full hierarchy page, to be consistent with the Class section
> that immediately starts with classes, the Data Types section could
> immediately start with data types, not with the type "DataType".
> Additionally, in a similar manner to Enumerations, the instances of
> Boolean, True and False, could be in a different text style to the data
> types (if they should be listed there at all).
>
> I hope people might find this useful.
>
> Anthony
>
> On Sat, Jun 16, 2018 at 4:40 PM Thad Guidry <thadguidry@gmail.com> wrote:
>
>> I've started the new "Help Our Users!" mission
>> https://github.com/schemaorg/schemaorg/issues/1958
>>
>> -Thad
>>
>>