Dvc.org: syntax: review bullet point lists throughout docs

[jorgeorpinel]

Per https://github.com/iterative/dvc.org/pull/490#discussion_r305564376

Using these guidelines:

• https://www.businesswritingblog.com/business_writing/2005/12/the_best_of_bul.html
• https://www.businesswritingblog.com/business_writing/2012/01/punctuating-bullet-points-.html

[shcheklein]

@Naba7 before we jump into implementing this, could you please summarize the set of rules we are applying, so that we all on the same page and have a guideline how to put it in the future.

[jorgeorpinel]

Some rules to consider:

• Avoid using bullet lists for text including of more than 2 sentences. Existing cases of this should be converted into regular paragraphs in sub-sections (with ### headings, for example).
• Avoid using bullet lists for steps to follow in examples. These should also be converted into regular paragraphs or sentences (usually intermixed with sample code bocks).
• Begin the bullets with an upper case (capital) letter except for options in command references, which start with "`option` - " (we use lower case after these hyphens).
• End each bullet with a period . unless its just a short phrase or sentence fragment, in which case we use no punctuation:
  
  
  
  • Like this
  
  
  • Or this
  
  
• Another exception to the rule above can be when bullets complete a stem as the following sub-list will exemplify. In this case we:
  
  
  
  • also start the bullet with lower case.
  
  
  • finish each bullet with a period even when they're just fragments.
  
  
• Don't mix full sentence bullet lists with short phrase/ fragment ones or with stem-completing ones.

UPDATE: Also

• leave no empty spaces between bullets, except when (some of) the bullets contain more than one sentence?
• What about sub-lists? (second-level indented bullets) There's a few of those out there...

[shcheklein]

Check also this: https://docs.mattermost.com/process/documentation-guidelines.html#bullet-lists

1-2. - Be really careful with this. ### can create too much visual noise if you split small lists.

3-4. I would follow the guide from the link. Only if it's a full sentence item start it with a capital and end with period. Otherwise, lower case is fine and no punctuation.

Otherwise looks great! May be should incorporate into a style guide section (similar the link above). For now it can be a subsection in the docs contributing guide.

[shcheklein]

@jorgeorpinel @Naba7 please review my suggestions, and let's come up with a final version of the rules.

[jorgeorpinel]

OK. I added the following bullet list guidelines to the contributing docs guide:

Bullet lists shouldn't be too long, nor each bullet's text (3 sentence
paragraphs max.) The bullets can begin in lower case and have no ending
punctuation if they're not full sentences (otherwise end with period .). The
bullets can be separated by an empty line if they contain short paragraphs.

What do you think?

p.s. you can see the change in https://dvc-org-pr-490.herokuapp.com/doc/user-guide/contributing-documentation (implemented in 1bf9880)

[shcheklein]

I left a comment there, probably we should mention that it should start with a capital letter if it's a sentence, no?

[dnabanita7]

I left a comment there, probably we should mention that it should start with a capital letter if it's a sentence, no?

yes, if they are phrases we can start with small letters.

[dnabanita7]

Sorry I was busy with my college thing so couldn't catch up early.

[dnabanita7]

@shcheklein @jorgeorpinel
1) In contributing.md , contributing-documentation.md, collaboration-issues.md What to do with these bullet points?
2)

UPDATE: Also

* leave no empty spaces between bullets, except when (some of) the bullets contain more than one sentence?

* What about sub-lists? (second-level indented bullets) There's a few of those out there...

I think keeping one line space when there are more than two lines will be appropriate.
If phrases then no fullstops otherwise if it is a full sentence then using fullstops.

3) In what-is-dvc.md we have more than two sentences and making them into subpoints seems pretty weird to me.

[jorgeorpinel]

@Naba7

1. In contributing.md , contributing-documentation.md, collaboration-issues.md What to do with these bullet points?

I fixed he first 2 in a448573 which will get merged with my latest PR. Don't worry about the last one, I'll address that for issue #425

[jorgeorpinel]

I think keeping one line space when there are more than two lines will be appropriate.
If phrases then no fullstops otherwise if it is a full sentence then using fullstops.

Hmmm yes maybe measuring them by number of lines is better. But we're already said The bullets can be separated by an empty line if they contain short paragraphs. so let's just remember about this internally I guess?

And what do you mean by "fullstops" ?

In what-is-dvc.md we have more than two sentences and making them into subpoints seems pretty weird to me.

Thanks for the note. I'll address for issue #425 as well.

[dnabanita7]

Hi! @jorgeorpinel
We say period as fullstops.
Yes, we will use one line gap after short paragraphs and no need to mention it again.

[jorgeorpinel]

OK, "full stop" as in British "period". Gotcha.