Bullets consistency

[skalee]

In common_ds.apib, both * and + are used as bullets when listing object attributes: https://github.com/riboseinc/ribose-api/blob/53f3e33e4cbeb2d5dfdd1d9d60656808ef483d72/sections/common_ds.apib#L151-L175

And sometimes, they're even mixed in one section: https://github.com/riboseinc/ribose-api/blob/53f3e33e4cbeb2d5dfdd1d9d60656808ef483d72/sections/common_ds.apib#L177-L181

Let's make it consistent. Do we go with plus sign, or asterisk?

[ribose-jeffreylau]

Thanks @skalee for bringing this up! This has slipped past my radar...

Personally, I'd prefer the option that is easiest to type.

Are there any other options apart from * and +?

[ronaldtse]

Let’s go with asterisk? It’s probably the most used syntax in markdown.

[ribose-jeffreylau]

If I were to pick two bullet point styles, I would pick * or -.

• - is one less key stroke than + & *, and is closer to the home row than +.
• * is one more key stroke than -, but is the closest to the home row.

[skalee]

To me, either is good. The + might have one slight advantage (or disadvantage) that it's the same mark we use to introduce API Blueprints sections, so it's probably easier to have one bullet style across whole documentation (unless someone wants to enforce different style for attributes).

[ronaldtse]

I spoke with @ribose-jeffreylau and he preferred the “-“ earlier. I’m fine with either “-“ or “+”. However we should keep the same bullet character be it “-“ or “+” consistent in the document (given they mean the same things).

[ribose-jeffreylau]

@skalee Actually, would it be possible to use - for API Blueprint sections as well? Then we could use - everywhere.

[skalee]

@ribose-jeffreylau Yes, - are totally allowed, however pluses seem to be favoured by API Blueprints maintainers:

NOTE: While this specification uses pluses (+) as list markers you can use any Markdown list syntax using asterisks (*), pluses (+) and hyphens (-) interchangeably. (source)

[ronaldtse]

Nice find @skalee. Let’s go with the “-“ for now at least it saves us some shift-presses :wink:

[ribose-jeffreylau]

Cool! Thanks @skalee !

I guess that if one day we want to convert to +, it would just be a sed away anyway.

[skalee]

Going with - then.