spree/spree-guides

Markup/Markdown Consistency

danabrit opened this issue · 5 comments

danabrit commented

Segue from a conversation on the spree-user mailing list, I propose we standardize a set of HTML markup conventions for the guides.

RandyT asked if any publishers have a set of standards. I'm sure there are plenty, but I propose we follow the Rails Guides' API conventions for consistency. If there are no major conventions I can own writing these up as part of the README for this project in a (near) future commit. I'm sure we'll probably stumble on some conventions we need that aren't in the Rails Guides, or vice versa.

Thoughts?

From the list:

I'd like to get some consensus on documentation markup conventions. I really think it would help to make all of the docs look a lot more uniform. Obviously, extracted code needs to have the triple-ticks around it to mark it as code, but what kind of markdown habits do we want to use for these:

  • Model names in prose (e.g. "When you create a Product object…")
  • Buttons (e.g. "Click the Update button.")
  • Names of links (e.g. "Click the Images link.")
  • Section names (e.g. "In the Purchase Funnel section, you will find…")
  • Field names for forms (e.g. "Enter 'Tshirt' in the Name field.")
  • State names (e.g. "At this point the order is in the completed state.")

What should be bold? What italicized? What underlined? What marked in ticks? What should have no markdown at all?

Obviously, this isn't an exhaustive list, and it's not meant to be. I would hope we could add to this over time and put it in the README for spree-guides for posterity.

radar commented

Not decreeing anything. These are just my guidelines:

  • Model names should always begin with an uppercase letter to distinguish them from the concepts they represent. If we're referencing the class name itself, then that is what should go inside ticks. i.e: "The Product model tracks the different products in your store". Having the namespace is optional.
  • Buttons should always reference the correct label, and can optionally have their names quoted. Same goes for links and section names and field names, but not state names.

Bold is used like this:

  • attribute_name - Short description of attribute goes here

If we're emphasising anything, that should be italicised.

schof commented

Rails conventions don't seem to be very complete IMHO. I think we'll have
to come up with some of our own. I'm open to anything reasonable. The
ones you proposed earlier plus Radar's comments seem like a good start.

On Sun, May 12, 2013 at 7:30 PM, Ryan Bigg notifications@github.com wrote:

Not decreeing anything. These are just my guidelines:

  • Model names should always begin with an uppercase letter to
    distinguish them from the concepts they represent. If we're referencing the
    class name itself, then that is what should go inside ticks. i.e: "The
    Product model tracks the different products in your store". Having the
    namespace is optional.
  • Buttons should always reference the correct label, and can
    optionally have their names quoted. Same goes for links and section names
    and field names, but not state names.

Bold is used like this:

  • attribute_name - Short description of attribute goes here

If we're emphasising anything, that should be italicised.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/117#issuecomment-17787487
.

danabrit commented

I pushed a start to a set of conventions on the README. I want to start going through and standardizing, but I want to make sure what I've written up is acceptable first. I can add more, obviously, but I started with what @radar listed. Is the README the appropriate place, or should we move the conventions to the contributing guide?

radar commented

I think both the README and the guide are good places for it. Put it in both.

On Mon, Jun 3, 2013 at 8:58 AM, Dana Jones notifications@github.com
wrote:

I pushed a start to a set of conventions on the README. I want to start going through and standardizing, but I want to make sure what I've written up is acceptable first. I can add more, obviously, but I started with what @radar listed. Is the README the appropriate place, or should we move the conventions to the contributing guide?

Reply to this email directly or view it on GitHub:
#117 (comment)

danabrit commented

This has been started and is working well (it's in the README and the contributing guide), so I'm going to close this issue.