Carbon: Content strategy for component's README

[shixiedesign]

Problem

The READMEs of components right now are not written very well. We have moments where every line is a Heading 4 (see below), which causes hierarchical confusion. Some content might also need update to be relevant to V10.

Task

Define a guidance for how to write component README, so that a developer can follow the guidance write/edit the README to have clear Heading2-4 and consistent use of code snippets. Remove any use of Heading 5s.

---

Here are some bad moments from the current state:

This moment is from file uploader. Everyone line is an Heading 4. I don't know if only the ES2510 belongs to Getting component class reference or all of them do.

H4 should not be a sentence, or have multiple clauses, eg from content switcher:

Code snippet styling needed for all CSS classes and selectors, such as here:

[asudoh]

@shixiedesign Thank you for reporting! Wrt <h4> - Any thoughts on what we should do instead?

[joshblack]

@shixiedesign did you mean to create this in the website repo?

[shixiedesign]

@joshblack No actually! For content in component's Code tab in the website, we are currently just pulling the READMEs from this repo so website folks have no control over it. We need to get the content structure right in here to start with.

[joshblack]

Cool! Sounds good 😄

[asudoh]

@shixiedesign Any words on what we should do with <h4>? Thanks!

[shixiedesign]

Sorry not yet! @asudoh Let me see if a content designer is around to take this issue on.

[claycrenshaw]

I'm not totally sure I understand the problem here. . . Is it concern that "Example - Changing the active item" is not appropriate wording for a H4? @shixiedesign

[shixiedesign]

@claycrenshaw Yeah that's how I feel. I don't know if "example" should be a heading. It can just be a paragraph. Another instance is this on moment on file uploader. All those H4s should just be paragraphs.

[shixiedesign]

I explained it to Conner too coz he's here. He said he will take a look at this issue FYI @claycrenshaw

[claycrenshaw]

I don't really see the problem with this wording... @shixiedesign where are you getting this rule about how to word H4s from? Thanks!

[jeanservaas]

I think the issue is that there's a clear hierarchy problem... You don't know which H4s belong to which sections in some cases because there are so many H4s piled on top of each other. For instance... do all three of those code snippets belong to "Getting component class reference?" or does just ES2015 belong to that.

We also need to manually fix those instances where there is not margin bottom on that H4... it cannot sit on the code snippet. We do not want to add margin bottom to all of our H4s... but I'm wondering if there's another more programatic way to solve it.

This is a big issue and it was the subject of a lot of Mike and Sadek's QA'ing. We need to solve it in the upcoming sprint. Also, I believe dev also needs to comb through this content and see what needs to be updated for X. Some of this stuff may not be relevant anymore.

[joshblack]

Is there any chance we could keep using the same heading levels, and add appropriate styles when being pulled into the design site? One of the primary ways of consuming these READMEs is directly through GitHub, for example: https://github.com/IBM/carbon-components/tree/master/src/components/file-uploader and any changes should keep that in mind.

[asudoh]

Thanks @shixiedesign and @jeanservaas for your feedback and @claycrenshaw for your help!

For instance... do all three of those code snippets belong to "Getting component class reference?" or does just ES2015 belong to that.

It's the former. Would this be <h4> and <h5> or <h4> or simple bold (**something**)?

Also looking forward to hearing what Example - Something should be changed to. Thanks!

[aagonzales]

Maybe we should start from the beginning. Is there a template/guidelines for how these read.me pages are currently written? Is there a specific reason why H2s aren't used in the markdown?

[asudoh]

Good question @aagonzales - I just have been trying follow the existing README.md files, though "Example - Something" stuff was definitely my addition (I attempted to structure it to best fit into other portions in README.md files). Good if we can define one.

[claycrenshaw]

I think @aagonzales has a great point. We don't have clear guidance on how to structure these pages with H tags in the first place. I think that as we re-evaluate the component pages as a whole, we will definitely need to be deliberate in establishing these guidelines for the readme files.

[claycrenshaw]

@joshblack @jeanservaas I definitely favor the progammatic solution to this H4 spacing issue. Manually adding in line breaks runs the risk of adding a bunch of extra work down the line (and it's just not the best-practice approach IMO)

[aagonzales]

This sprint:

• [ ] quick fixes to match current site hierarchy until full page re-design is done.
• [ ] make sure it doesn't break read.me doc on repo vs website code page.

[shixiedesign]

Related issue: https://github.com/carbon-design-system/carbon-website/issues/791

Discussion during design crit:

• Definitely need to change H5s to paragraphs
• Potentially all the headers in README can be bumped up to H2-H4. Currently they start at H3.
• @connor-leech @vpicone could take a pass on some of the READMEs and team will help with resolving problems
• check what Anna said above: https://github.com/IBM/carbon-components/issues/1769#issuecomment-464820585

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. Thanks for your contributions.

[shixiedesign]

Not stale, unfortunately.

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. You can keep the conversation going with just a short comment. Thanks for your contributions.

[connor-leech]

I believe @mattrosno is looking at a long term plan for creating updated readmes.

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. You can keep the conversation going with just a short comment. Thanks for your contributions.

[shixiedesign]

not stale

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. You can keep the conversation going with just a short comment. Thanks for your contributions.

[stale[bot]]

As there's been no activity since this issue was marked as stale, we are auto-closing it.