Add callout boxes to handbooks

[siobhan]

Nacin has put together a suite of plugins for the handbooks: [10].

I'd love to see some callout boxes added so that doc writers can flag different things in the text. Here's what would be useful:

• Draft - for marking articles as in progress
• Important - for telling the reader about something important
• Warning - for alerting readers to potential issues
• Tip - for an advanced tip
• More Information - to alert a reader that they can find more information on this elsewhere
• Next Steps - to tell the reader where to go next

Am open to more, but we don't want to have too many because we want it to be easy for readers to become familiar with them.

Jerry has already done some handbook mockups here: ​http://make.wordpress.org/docs/files/2013/03/WP_Handbooks_comp-01a.png and I think they'd be a great place to start.

The P2 child theme is here: sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-p2/

[siobhan]

Should have added - would like to see these as shortcodes. For example;
[draft]
[tip]
[important]
[more-info]
[next-steps]

[jerrysarcastic]

In chatting with Eric (sewmyheadon) there was some confusion as to what the difference would be between [tip] and [more-info] and how they would be used. To avoid having future editors ask the same question, I consolidated them for the time being. I've also added a new shortcode called [note] for your consideration.

Shortcode	Describe	Style
[checklist]	Adds checkmarks the introduction checklist. To be used in conjunction with a <ul> element.	Checkmarks in <ul>
[more-info]	Additional information, including asides, links to external resources, tips and hints, etc. Not essential to completing the topic, but good to know.	Blue box
[note]	Highlights an important aspect of the topic being discussed. Something to watch out for be aware of.	Yellow box
[warning]	Alerts the reader to a potential issue or problem. Something to be avoided.	Red box
[next-steps]	Tell the reader where to go next. Offers jumping off points, links to external resources, or even the next topic (in series) for that handbook.	Green Box

About the [draft] shortcode, How would this be used in practice? To mark sections (of an existing page) that are still in draft form or to mark an entire page as a draft?

[jerrysarcastic]

Added new [note] callout

[kpdesign]

Replying to jerrysarcastic:

In chatting with Eric (sewmyheadon) there was some confusion as to what the difference would be between [tip] and [more-info] and how they would be used. To avoid having future editors ask the same question, I consolidated them for the time being. I've also added a new shortcode called [note] for your consideration.

Just my thoughts:

[tip] would be used within the content for a brief bit of info (blue box). I think notes could be included in this as well, not sure we need a separate [note] shortcode?

[next-steps] block will include Next Steps, Credits, Learn More, References, More Info, etc. - all the things that go at the end of the page (green box). Not sure we need a separate shortcode for [more-info].

[warning] will also be used within the content to alert read to potential problems (red box).

[checklist]: To my knowledge, there shouldn't be any checklists on the introduction page once the handbooks are complete. Can you give me an example of something we would need a checklist for in a handbook? Also, couldn't we use the P2 checklist functionality (o Item 1, o Item2, etc.) instead? Edit: I looked at your mockup and see where you are using checklists at the beginning (what we will cover). Could also use that for the What You Will Need Before Starting list at the beginning of the tutorials in CCH.

About the [draft] shortcode, How would this be used in practice? To mark sections (of an existing page) that are still in draft form or to mark an entire page as a draft?

I think [draft] would be used to mark an entire page as a draft. The block should probably include the person's name who is working on the page so other authors could contact them about collaborating or corrections. I could also see it used on a page section, but not often.

When we were in Cincinnati, you, @drewapicture and I talked about these shortcodes, and came to the conclusion that we really only needed 5 - [draft], [red], [blue], [green], and [yellow] - to keep it simple. A list could be made for authors to reference which shortcodes are used for what items, and included in the style/template guide in the Make/Docs handbook. Regardless of what we call them, I think we need to keep the number of shortcodes to as few as possible.

I love how the boxes look, but do have a style suggestion: please don't italicize the text in the callout boxes, as the author may need to insert their own italic styling for a portion of the text in the box.

[DrewAPicture]

+1 to comment:5 :)

[jerrysarcastic]

Replying to kpdesign:

I think [draft] would be used to mark an entire page as a draft. The block should probably include the person's name who is working on the page so other authors could contact them about collaborating or corrections. I could also see it used on a page section, but not often.

Which makes it sound like some mechanism other than a shortcode might be better suited for this. I have seen draft callouts used for sections in other forms of documentation (Rails, I think) and it was a bit of a mess to have the page littered with sections marked as drafts.

When we were in Cincinnati, you, @drewapicture and I talked about these shortcodes, and came to the conclusion that we really only needed 5 - [draft], [red], [blue], [green], and [yellow] - to keep it simple.

Totally agree! Except for the [draft] shortcode (which I have as a [checklist] instead) I think 5 is the magic number. What we name them is up for debate, but I'd hate to have more than that. I think we'll also add buttons into the post editor for these shortcodes, which would also help cut down on confusion.

I love how the boxes look, but do have a style suggestion: please don't italicize the text in the callout boxes, as the author may need to insert their own italic styling for a portion of the text in the box.

I think Sara will be looking at the design when she returns, but I can see where you are coming from, and it is easy to avoid that on the actual site. :)

[samuelsidler]

Let's do this:

Shortcode	Describe	icon
[blue]	Information, links to external resources, tips and hints, etc.	dashicons-info
[yellow]	Can be used to note a draft page or any sort of behavior they need to watch out for.	dashicons-admin-post
[red]	Alerts the reader to a potential issue or problem. Something to be avoided.	dashicons-dismiss
[green]	Can be used to tell reader "what's next" or show good behavior.	dashicons-lightbulb

Let's start with those. We'll use the design from @jerrysarcastic above.

The key to the above working well is that we need to allow the icon to be changed in the short code to any available dash icon. That way, we don't prescribe too much meaning to each short code, but do give each a default meaning. Each handbook may have different uses for each short code, which we can document in the make/docs style guide.

Note that this knocks us down to only four. I'd be fine with adding a fifth (grey/gray) that uses dashicons-admin-comments as its icon. But I think four is probably enough for now.

What say you?

[siobhan]

I'd like to keep it to four or five shortcodes, however the shortcode name should not be a colour, it should be what it's used for.

The problem with using a colour is that then we need an additional reference to tell people what the shortcode is for, and it's too easy for people to think "hey, I just want a pretty colour so I'll use this box."

Let's stick with
[info] - additional information, more information, more advanced information
[tip] - a tip that doesn't quite fit in with the body of the text but that is useful for people to know
[warning] - a red box with stuff that should be avoided or definitely done
[alert] - something that we need to alert the reader to - that the page is a draft or needs updated or whatever.

[DrewAPicture]

I've submitted a ​pull request on the wporg-developer repo for the four shortcodes described in comment:10. Still need is some styling effort to add the icons.

Currently the shortcode outputs look like this:

[coffee2code]

In 879:

Handbook plugin: add shortcodes for callout boxes:

• Adds shortcodes [info], [tip], [alert], [warning]
• Adds default styling

Fixes #1.
props DrewAPicture.

[coffee2code]

Changes from @DrewAPicture's PR:

• Modified from patching wporg-developer theme to instead apply to Handbook plugin.
• Fixed overflow bug (apparent when callout runs into Topics box).
• Added dashicons (as requested by @samuelsidler) and adjusted spacing accordingly
• Increased contrast between the background colors and the borders/dashicons.
• Changed class name.

[coffee2code]

Callout boxes as they should look after [879].

[coffee2code]

Example of multi-line text.