Thoughts on bullets in docs

(Taylor Barnett) #1

I’ve found this article from the Nielson Norman Group something I return to on how to best break up documentation in bullets so users can easily read the information:

Anyone else have strong feelings on how bullets should be represented in docs? Or have thoughts on the article?

(Robbins) #2

Love My Lists

I grew up using the Roman numeral system for creating outlines and I wish that would come back, but for now, I have settled comfortably in with bulleted lists. For lists in general, I really enjoy:

  • The efficiency
  • The clean style
  • The familiarity

Random Observations

I see issues with parallel structures quite a bit and I would love to see other styles of bullets. The one dot is great, but it feels a bit played out. I also don’t see side by side lists a ton, but I wouldn’t mind it as a change of pace content block. And what ever happened to the Roman Numeral System? I can’t even remember it that well. I think it was something like this:

Anyways, lists are awesome no matter what form they are in. Perfect for reading and breaks up content nicely. Cheers Taylor! :owl:

(Einnes) #3

Re: bullets

If you are making a list and the contents can go in any order, you should use a dot or whatever that does not denote a specific order.

If you are making a list and the contents go in a specific order, you should use numerals instead of bullets.

Also bullets are a great way to break up a page and also make content easily digestible if the bullet points are kept short.

The roman numeral system I haven’t seen in ages lol… I think that is a great system for writing outlines for big papers or projects though, and I’d still use it for that. :slight_smile:

(Taylor Barnett) #4

Roman numerals feels very “academic” these days. I don’t really see them in API documentation much.