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 😉

[akordowski]

@subatoi I noticed that there are texts like **Allow Marketplace actions by verified creators:** where the colon or period is inside the bold formatting. Therefore I would suggest to use the same formatting for single words (**Keyword:**). What do you think?

[subatoi]

@akordowski OK 👍, that makes sense, thank you—let's go with inside the bold formatting. Thanks for giving this such careful thought!

[akordowski]

@subatoi @nguyenalex836 The PRs for the bold formating are available.

For text cases like If you selected **Allow for specific organizations**: I left the formatting as is.

[nguyenalex836]

@akordowski Thank you for all of this work! I'll be reviewing these PRs soon 💛

[akordowski]

@nguyenalex836 At least the PRs are not so big this time 😆

[nguyenalex836]

All three PRs have been merged! 🍾 Thank you so much @akordowski for putting all of this time and effort into fixing these inconsistencies, and for working with so collaboratively with @subatoi 💛

[akordowski]

@nguyenalex836 @subatoi

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

There still remains the dash formatting. How would you like to have solved that?

[subatoi]

Hi @akordowski 👋

There still remains the dash formatting. How would you like to have solved that?

Would you be open to creating a new issue for that?

If possible it'd be great if you could show me the example where you found the inconsistency within the same article.

Grammatically speaking Text—Text is "proper" (also conforms to Microsoft style) but it depends on the usage: they might not all be used in that way.

[akordowski]

@subatoi

Would you be open to creating a new issue for that?

Yes, of course 😉

If possible it'd be great if you could show me the example where you found the inconsistency within the same article.

I will try to find it again.

Grammatically speaking Text—Text is "proper" (also conforms to Microsoft style) but it depends on the usage: they might not all be used in that way.

If you can provide a rule how I can distinguish when to use which that would be great.

[subatoi]

If you can provide a rule how I can distinguish when to use which that would be great.

If we're talking general sentence structure to describe how to do something, then it would be with no spaces. For example:

"The quick brown fox jumped over the lazy dog—he was a wily one, that fox."

But if it's replicating something on the GitHub UI itself, then regardless of whether what's being replicated is grammatically correct, we'd have to copy it exactly. I'm not aware of places in the docs where that's the case off the top of my head, but it wouldn't surprise me if they existed, I'm afraid... does this make sense?

[akordowski]

does this make sense?

Yes, thank you. As I do the changes manually I will pay attention to it.

[akordowski]

@subatoi

If you can provide a rule how I can distinguish when to use which that would be great.

Found an example. Here is the dash used with spaces and here without.

There are also cases like this, where the dash separates multiple parts of a sentence:

For commits, there is the author — the person who wrote the code — and the committer — the person who added the commit to the tree.

The search for dash with spaces returned only 23 results. As I am non-native speaker, maybe the team could look into it. I would leave it then. Is that ok for you?

[subatoi]

Got it, thank you!

Found an example. Here is the dash used with spaces and here without.

For any site policy documentation, I wouldn't make any changes just yet, because they're subject to specific legal considerations. If you did want to make any suggestions or changes to those docs in future, @nguyenalex836 would be able to help you with that (it's a slightly different process).

For the other point you raised:

The search for dash with spaces returned only 23 results. As I am non-native speaker, maybe the team could look into it. I would leave it then. Is that ok for you?

That's absolutely fine. Thank you for your help! I'll create an issue to handle this internally.