Inconsistent text formatting

[akordowski]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

Multiple articles.

What part(s) of the article would you like to see updated?

I noticed that there is a inconsistent text formatting regarding the text **Keyword**: Text (559 results) and **Keyword:** Text (331 results).

I don't know if there are any conventions regarding using a colon with a bold text, inside or outside. But from the formatting/style perspective the **Keyword:** Text seams to make more sense, as the keyword and the colon are a unit in the text.

EDIT:
There is also a inconsistent usage of the dash — character. There are usages of Text—Text and Text — Text, even in the same article.

Additional information

I could provide a PR for this issue.

[nguyenalex836]

@akordowski Hello! 👋 Thank you for opening this issue!

But from the formatting/style perspective the Keyword: Text seams to make more sense, as the keyword and the colon are a unit in the text.

As I couldn't find anything in our style guide referencing guidelines for this, I'm inclined to agree with you 💛

I'll get this up for review just so we can get a second opinion on this, as well as the inconsistency between usage of Text—Text and Text — Text

[subatoi]

Hi @akordowski 👋

You're correct that this isn't consistent 👍

I don't know if there are any conventions regarding using a colon with a bold text, inside or outside. But from the formatting/style perspective the Keyword: Text seams to make more sense, as the keyword and the colon are a unit in the text.

The main reason we use bold is for emphasis (see https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#emphasis). Generally speaking, as long as we're consistent, it shouldn't matter which we use, and I agree with you that **Keyword**: Text makes more sense (and is the most common one as of now, anyway).

It's possible there are some minor edge cases which may require one or the other. As such, if you're interested in making this contribution, if possible, I'd recommend splitting it into multiple PRs so it's easier for us to review.

There is also a inconsistent usage of the dash — character. There are usages of Text—Text and Text — Text, even in the same article.

I agree with you here, too, but if you're interested in a contribution for this, as well, then I'd kindly request that you open a new issue so we can separate the work.

Thank you again!

[akordowski]

Hi @subatoi

Generally speaking, as long as we're consistent, it shouldn't matter which we use, and I agree with you that Keyword: Text makes more sense (and is the most common one as of now, anyway).

Acctually I meant the **Keyword:** Text format.

If you can tell me which format the team prefers for both cases, then I would provide PRs with the fixes. Thank you!

[subatoi]

Hi @akordowski 👋

I meant the Keyword: Text format.

Generally as long as we're consistent I'd say it's not hugely consequential, but purely on the basis that **Keyword**: already has far more instances, I'd suggest we go with that.

To make sure there are no strange edge cases, if you're interested in taking this work on, would it be possible for you to start with some smaller PRs?

Many thanks!

[akordowski]

would it be possible for you to start with some smaller PRs?
Yes, sure. How small? 😉 The PRs are limited to 300 due the linter, so I am always pay attention to that.

FYI: Could provide the changes towards the weekend/next week.

[subatoi]

Yes, sure. How small? 😉 The PRs are limited to 300 due the linter, so I am always pay attention to that.

I would suggest you could start with sub-directories under the content directory in order, so it's easier to keep track of, and once you first hit >50 changes, you could submit a PR (it doesn't matter if it goes above 50, this is just a suggestion).

I think we'll soon realise that we're safe to push ahead with bigger changes, and at that point I'd be comfortable recommending that you raise bigger PRs.

Does this sound sensible? I'm just trying to make sure we don't create unnecessary work for you.

FYI: Could provide the changes towards the weekend/next week.

That's absolutely fine: we won't open this issue up to other contributors. Since this doesn't negatively impact user experience, we don't consider this urgent, but we'd appreciate your help in changing it.

Thank you again!

[akordowski]

I would suggest you could start with sub-directories under the content directory in order, so it's easier to keep track of, and once you first hit >50 changes, you could submit a PR (it doesn't matter if it goes above 50, this is just a suggestion).

I think we'll soon realise that we're safe to push ahead with bigger changes, and at that point I'd be comfortable recommending that you raise bigger PRs.

Ok, will see what I can do 😉