On 03/25/2015 11:28 PM, Pete Travis wrote: > Hi all, > > I'm working through the logistics of consuming arbitrary markup > formats. It would be helpful to have a standardized way to describe a > document. The example below is YAML, because it is easy to digest, > write, and read, and I think the structure covers the important > attributes without being cumbersome. > > --- > title: Example Document > stub: A representation of a document description standard. > abstract: > > This could be an example document. > It could explain example documents. > It could use examples to explain what a document is. > It is none of these. > author: > - Carlton Bentleby > - Vizek Glibensky > - Obvious Pseudonym > taxonomy: > theme: Contributions > scope: Documentation > track: Metadata > project: anerist > tags: > - yaml > - metadata > - proposal > - standard > --- > > title, stub, and abstract are self-apparent. > > Author seems like a MAY item; for a standard to go further than our > group, it'll need that, but staking a line around a collaborative work > MAY discourage collaboration. > > The taxonomy can be in any order, but in function it's hierarchical; > theme at a very abstract level, scope being more refined, track gets > down to a specific topic. The project differentiates between different > approaches to addressing a given topic (and hey, people _will_ look for > answers on a specific solution). > > Tags give some SEO value, could help crossreferences, site search > features... all that stuff that tags do. > > What do you think? How can it be better? > Establishing some sort of categorization for content in each work we want to publish is an imperative for the CI-driven site buildsystem I'm working on. I'd really like to apply the expertise in the group to forging this into a tenable standard, and require it for future contributions. For our existing guides, there was some concern expressed about maintaining the abstract and stub (ie subtitle) in both the Docbook markup and in the metadata, so I've already built a utility to programatically extract that information and update the metadata file. It occurs to me now that the author list could be retrieved as well...TODO. I'll start the conversation by pointing out two attributes that are missing from the example. First, the license; we're CC-BY-SA by default but should be able to accept and state any acceptable license. The second came to mind after Ryan's question in that other thread; labeling a 'class' or 'type' of a document, ie 'book', 'article', 'tutorial', etc. Most of these fields should have predefined acceptable values. Approved content licenses, acceptable types, standardized taxonomy. We should discuss that too. -- -- Pete -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
