Move annotations to markdown file

[bradfrost]

I'm not sure if this is the exact right place to discuss this, but as I've been cleaning up the UI layer, I've been thinking about the role of annotations and how they might be able to be revised and/or moved or perhaps even removed in order to be more useful.

Current Implementation

The current implementation of annotations involves a file called source/_annotations/anntations.js. Within the annotations file, we can define an annotation like so:

{
  "el": ".c-header",
  "title": "Masthead",
  "comment": "The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content. It's using a linear CSS gradient instead of a background image to give greater design flexibility and reduce HTTP requests."
}

Are annotations needed?

The first question I'll ask is "do annotations need to exist?" What I mean by this is "are annotations fundamentally different than the base pattern definition/documentation?" If the answer to that is no, then annotations could be eliminated, and rather than showing distinct annotations, we could expose each child pattern's description/documentation in this view:

If annotations are indeed distinct from pattern description, then we should think about how to integrate annotations that into the formats and locations that we're standardizing on.

Format and location

So rather than the current implementation I'd propose something like this:

---
title: Masthead
element: .c-header
annotation: The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content. It's using a linear CSS gradient instead of a background image to give greater design flexibility and reduce HTTP requests.
---
Pattern description/documentation

I think this makes sense as we're moving all documentation and info around a specific pattern into markdown. That means we can remove the source/_annotations/anntations.js file and have everything under one roof.

Questions

1. Are annotations fundamentally different than pattern description/documentation?
2. Where should annotations live?
3. How should annotations behave?

/cc @pattern-lab/voting-members

[bmuenzenmeyer]

I think that annotations have limited use cases - the most prominent one being when highlights or callouts in are required inside template / page views. Their value comes from being able to call out a single portion of a complex piece of markup. Forest and trees at the same time.

Therefore, to me, they are NOT the same as a description at the template or page level, as they describe a subset, but COULD be the same as the description at the smaller scale. Even so, I suspect people would want to describe a pattern different than they may want to annotate it.

@bradfrost @EvanLovely in your experience working with clients, do you find yourself demoing whole patterns WITH annotations? I have not.

The proposed frontmatter markup makes sense, but it would have to be under something like the following to support multiple entries per pattern:

---
annotations:
   - title: Masthead
       - element: .c-header
       - annotation: The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content. It's using a linear CSS gradient instead of a background image to give greater design flexibility and reduce HTTP requests. 
    
---

I think that yaml is right. Either way. I am open to annotations being deprecated.

Removing a feature like this would trigger a more formal definition of what the Pattern Lab 2.X or even 3.X spec is. We have sorta skirted this issue so far and we may need to spend some time doing this for clarity's sake.

[bmuenzenmeyer]

@EvanLovely added you to the @pattern-lab/voting-members team just now

[bradfrost]

@bmuenzenmeyer, great idea to make annotations an array. That brings up more ideas I have around code documentation that I'll save for another time.

You're right annotations have limited use cases; I never really use them on my projects, but have been into multiple companies who make extensive use of them. Since the feature exists, I'd prefer to keep it in there. I'll think a bit more of the UX of annotations, but for now it sounds like a good next step is to get annotations into YAML

[EvanLovely]

@bradfrost @EvanLovely in your experience working with clients, do you find yourself demoing whole patterns WITH annotations? I have not.

Honestly... never! I always think they are awesome though and have a lot of potential! I'd definitely like to keep and support them.

Annotations array: :+1:

My vote: 👍

PS Folded these suggestions into mine about Pattern Meta in MD yaml: https://github.com/pattern-lab/the-spec/issues/34

[bmuenzenmeyer]

👍

[bmuenzenmeyer]

vote passes