Page MenuHome

Use of upper and lower case letters in Blender Manual
AbandonedPublic

Authored by Tuomo Keskitalo (tkeskita) on Sat, Dec 1, 12:11 PM.

Details

Summary

I propose that we specify the use of capital letters for Blender Manual (maybe also for the wiki?). Currently I'm a bit confused about when to capitalize words and when not to. It would be good for the manual reader if they can immediately distinguish between general use of words (like monitor screen) from a Blender-specific use (Screen) by the case. If this is already specified somewhere, please give a link. Any comments? @Aaron Carlisle (Blendify) ? @Tobias Heinke (TobiasH) ? @Inês Almeida (brita_) ?

Diff Detail

Repository
rBM Blender Manual

Event Timeline

There is already markup for labels found in the UI (such as the name of a tab). See: https://docs.blender.org/manual/en/dev/about/contribute/guides/markup_guide.html#interface-elements
If mentioning the Properties Editor, I would use a capital also in the second word. Same for Active Object, Bone Constraints, etc.
It's a choice whether we want to use special markup for this kind of thing, with different styling and potentially with a link to a reference page.
I have a feeling that it could be too much of it, both for a reader and also too much clutter for the writer.

Independently, I would change the following:

Spell checking is strongly recommended.

to

Spell checking is mandatory.

and

As a last resort you can add comment

to

As a last resort you can a add comment

Updated rule suggestion to All Nouns Capitalized.

@William Reynish (billreynish) : Is there some rule for coders about this? E.g. for tool tips etc.

@Inês Almeida (brita_) : I agree that often the context makes it clear what is meant, but not always. For example, I bumped into terms like screen, region and area in the UI section of the manual, whose context are easy to misunderstand. Maybe the term "user" is worst case example. If they were always referred consistently with capital first letter, it would be always clear for the reader that it is something Blender specific. It is true that reading about "Transform Panel in the Side Bar of the 3D Viewport" is not light reading, but I guess that Blender Manual is not supposed to be light reading..?

@Tuomo Keskitalo (tkeskita) For any command or tool, we use Title Case - as is the general standard in computing.

For tooltips we just write then as normal sentences. A while ago there was a debate if we should add a period at the end, which looks a bit silly when there is only one sentence, but is more consistent if there are more sentences inside the tooltip.

When referring to a feature from within a tooltip, I would think we should still use title case - eg 'This only works in Object Mode' rather than 'This only works in object mode'.

As Campbell already wrote in a comment in the Markup Style Guide: there are too many rules (capitalization, hyphenation, to the spelling of individual words: Internet, mip-map)
We can turn this in a fleshed out style guide with headlines or
keep it simple with: look what's there and copy it. i.e. the UI section defines the capitalization.

I think we should keep this in sync how organized the manual is and It's still too messy:
For example, after capitalizing all modifiers for hours I had enough, so the constrains are not capitalized.
If we want to expand this we should do it in one big step and also apply it, else we end up with both a messy guide and manual.

It's also to connect words Operator Panel vs. Transform panel (one of many panels).
~ it's complex.

Updated proposal to use conventions used in Blender user interface.

How about this change to use Blender's user interface conventions as an explicit rule? I think it should be explicit and not only something that is implied by interface elements section.

I agree that the current extensive list of rules should be condensed, because long lists are hard to absorb.

However I don't think that we should restrain ourselves from adding new rules, if those new rules make it easier for people to create documentation in a consistent style. Of course not all pages can immediately be corrected to conform to style regulations, but it is important that everyone has a clear picture about what the style should be, so that we can aim towards that uniform good quality manual. If goal is not set as clearly as possible, then the quality will remain poor.

It's also to connect words Operator Panel vs. Transform panel (one of many panels).

Can you please clarify this. Do you mean that if there are many panels then you should not capitalize the word panel like "Transform Panel"? I am not familiar with this kind of capitalization rule, is there more information somewhere?

If we choose to go with this Title Case style requirement, I think that the correction work would be made easier by using a find-replace bash command. D4052 shows an example for "Edit Mode". I'm sure its not perfect, but it seems to catch quite a few.

No, I don't have a reference for that; other than other programs of similar type/scale *cough GIMP ;).
The problem where to end: all upper for editors, modifiers, constraints, but not for other UI's (menus, panels, nodes).
With all upper we would end up with all words uppercase in some sentences.

The main question should be does it improves readability. It also interacts with other types of emphasis.
I mean these capitalization rule would affect almost every sentence, so we have to be careful with that and it would a lot of work to apply it.

The important thing is writing that down as a rule would not prevented these errors.
These edit modes were introduced by copy-pasting text from the Wiki/release notes and slip troughs (10/520 Edit Modes).
Yeah, these Mode capitalization have been done with regex.
Now that you noted that, therefore you have to ;) also fix the other modes and commit that.

So where does the manual deviate from the tech writing industry standard
or where is no clear standard (classic vs. modern):

  • UI elements: naming, capitalization
  • Editor state (mode): capitalization
  • Oxford comma: mixed in the manual; I think it doesn't matter (also D3131).
  • Contractions: - no, new ones where added.

Some reference of scale:

minimal: Django
small : Blender
medium: Mailchimp
big: OpenStack
bigger: IBM
huge: Microsoft Manual of Style (a book)