Define a consistent writing style for glossary entries #45893

New Issue

gandalf3 · 2015-08-25T03:21:58+02:00

gandalf3 commented

2015-08-25 03:21:58 +02:00

As many of the glossary entries are very inconsistent in style, here's a proposed "style guide" for glossary entries to follow

Avoid adding terms not found in blender's UI or the manual.
Avoid overly long entries. If an explanation of a complex term is needed, supplement with external links.
Avoid duplicating documentation; if explaining the term is the primary focus of another section of the manual (e.g. if the term is the name of a tool), either just link to that section, or avoid creating a glossary entry entirely.
Define the term before providing any further information.
Avoid using constructs like "It is" or "xyz is" before the definition.
Avoid repeating the term immediately or using it in the definition.
For external links included as an addendum, make the anchor text the title or subject of the target page. Optionally include the domain name after the link.

For example
This entry:

Displacement Mapping
Uses a greyscale heightmap, like Bump Mapping, but the image is used to physically move the vertices of the mesh at render time. This is of course only useful if the mesh has large amounts of vertices.

Would be written like this instead, putting a definition first:

Displacement Mapping
Method for distorting vertices based on an image. Similar to Bump Mapping, but instead operates on the mesh's actual geometry. This relies on the mesh having enough geometry.

This entry:

Doppler Effect
The Doppler effect is the change in pitch that occurs when a sound has a velocity relative to the listener.
When a sound moves towards the listener the pitch will rise.
When going away from the listener the pitch will drop. A well known example is the sound of an car passing by.

Would be written more like this, avoiding the immediate repetition of the term:

Doppler Effect
Perceived change in pitch that occurs when the source of a sound is moving relative to the listener.
When the source and listener are moving closer to one another, sound will rise in pitch.
When the source and listener are moving away from one another, sound will descend in pitch. For a real-world example, consider the sound of a car passing by.

This entry:

Curve
It’s a class of objects. In Blender there are Bézier curves and NURBS curves.

Would be written more like this, avoiding the "it's":

Curve
A type of object defined in terms of a line interpolated between Control Vertices. Available types of curves include Bézier and NURBS.

This entry:

Subdivision surface
Is a method of creating smooth surfaces, which can take a low polygon mesh as input.
Sometimes abbreviated to Subsurf.

See Wikipedia’s Catmull-Clark subdivision surface

Would be written more like this, placing the domain name after the link text:

Subdivision surface
Is a method of creating smooth surfaces, which can take a low polygon mesh as input.
Sometimes abbreviated to Subsurf.

Also see Catmull-Clark subdivision surface on Wikipedia.

As many of the glossary entries are very inconsistent in style, here's a proposed "style guide" for glossary entries to follow * Avoid adding terms not found in blender's UI or the manual. * Avoid overly long entries. If an explanation of a complex term is needed, supplement with external links. * Avoid duplicating documentation; if explaining the term is the primary focus of another section of the manual (e.g. if the term is the name of a tool), either just link to that section, or avoid creating a glossary entry entirely. * Define the term before providing any further information. * Avoid using constructs like "It is" or "xyz is" before the definition. * Avoid repeating the term immediately or using it in the definition. * For external links included as an addendum, make the anchor text the title or subject of the target page. Optionally include the domain name after the link. **For example** This entry: >**Displacement Mapping** >Uses a greyscale heightmap, like Bump Mapping, but the image is used to physically move the vertices of the mesh at render time. This is of course only useful if the mesh has large amounts of vertices. Would be written like this instead, putting a definition first: >**Displacement Mapping** >Method for distorting vertices based on an image. Similar to *Bump Mapping*, but instead operates on the mesh's actual geometry. This relies on the mesh having enough geometry. ------ This entry: >**Doppler Effect** >The Doppler effect is the change in pitch that occurs when a sound has a velocity relative to the listener. >When a sound moves towards the listener the pitch will rise. >When going away from the listener the pitch will drop. A well known example is the sound of an car passing by. Would be written more like this, avoiding the immediate repetition of the term: >**Doppler Effect** >Perceived change in pitch that occurs when the source of a sound is moving relative to the listener. >When the source and listener are moving closer to one another, sound will rise in pitch. >When the source and listener are moving away from one another, sound will descend in pitch. For a real-world example, consider the sound of a car passing by. ----- This entry: >**Curve** >It’s a class of objects. In Blender there are Bézier curves and NURBS curves. Would be written more like this, avoiding the "it's": >**Curve** >A type of object defined in terms of a line interpolated between *Control Vertices*. Available types of curves include *Bézier* and *NURBS*. ---- This entry: >**Subdivision surface** >Is a method of creating smooth surfaces, which can take a low polygon mesh as input. >Sometimes abbreviated to Subsurf. > >See Wikipedia’s [Catmull-Clark subdivision surface ](https://en.wikipedia.org/wiki/Catmull%E2%80%93Clark_subdivision_surface) Would be written more like this, placing the domain name after the link text: >**Subdivision surface** >Is a method of creating smooth surfaces, which can take a low polygon mesh as input. >Sometimes abbreviated to Subsurf. > >Also see [Catmull-Clark subdivision surface ](https://en.wikipedia.org/wiki/Catmull%E2%80%93Clark_subdivision_surface) on Wikipedia.

gandalf3 commented

2015-08-25 03:21:58 +02:00

Changed status to: 'Open'

gandalf3 commented

2015-08-25 03:21:58 +02:00

Added subscribers: @ideasman42, @GregZaal, @gandalf3

gandalf3 commented

2015-08-25 03:34:38 +02:00

I've noticed that

See Wikipedia's

Is a common pattern. If wikipedia links are acceptable in the first place (?), what about shortening that to

See Wikipedia

Where "Wikipedia" is a link?

I've noticed that >See Wikipedia's <article name> Is a common pattern. If wikipedia links are acceptable in the first place (?), what about shortening that to >See Wikipedia Where "Wikipedia" is a link?

Campbell Barton commented

2015-08-31 09:48:13 +02:00

This seems reasonable, did you check on guidelines other projects use?

https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary

Or what other applications use? (easy enough to find docs on other 3d apps)

This seems reasonable, did you check on guidelines other projects use? https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary Or what other applications use? (easy enough to find docs on other 3d apps)

gandalf3 commented

2015-08-31 10:25:06 +02:00

@ideasman42 Good idea!

Looked around at a few glossaries for 3D programs, and they seem to follow a similar writing style as suggested here.

Reading the MDN guide made me think of some more questions however:

Should there be a preferred (but maybe not strictly enforced) max length? There are a few somewhat lengthy definitions in the BM glossary.
IMO I don't really see anything wrong with longer entries (within reason), provided that they start with a shorter (if less detailed) definition which can stand on it's own and extra paragraphs are only used to provide more detail.

Should external links be encouraged? Or discouraged? Perhaps they could be useful for explaining concepts like non manifold geometry without cramming a mini-article into a few paragraphs, but also not sure if linking to just anywhere would be good (e.g. would links to stackexchange be acceptable?)

@ideasman42 Good idea! Looked around at a few glossaries for 3D programs, and they seem to follow a similar writing style as suggested here. Reading the MDN guide made me think of some more questions however: Should there be a preferred (but maybe not strictly enforced) max length? There *are* a few somewhat lengthy definitions in the BM glossary. IMO I don't really see anything wrong with longer entries (within reason), provided that they start with a shorter (if less detailed) definition which can stand on it's own and extra paragraphs are only used to provide more detail. Should external links be encouraged? Or discouraged? Perhaps they could be useful for explaining concepts like non manifold geometry without cramming a mini-article into a few paragraphs, but also not sure if linking to just anywhere would be good (e.g. would links to stackexchange be acceptable?)

Campbell Barton commented

2015-08-31 18:33:25 +02:00

@gandalf3

re: long descriptions:

In general, discourage... if some concept is complex, link to a page or a site with more info.

There are some exceptions where it can be OK though.

For example - When there is a Blender spesific term, which needs some comprehensive explanation.
In that case it makes sense to include in the glossary ... unless its getting into documenting Blender's it's self... and in that case we should probably have the information in the manual its self (glossary can be kept short, and link to a manual page).

re: external links:

I don't see why not? But don't think we need more than 1-2 ... per term, if any.

@gandalf3 ---- *re: long descriptions:* In general, discourage... if some concept is complex, link to a page or a site with more info. There are some exceptions where it can be OK though. For example - When there is a Blender spesific term, which needs some comprehensive explanation. In that case it makes sense to include in the glossary ... unless its getting into documenting Blender's it's self... and in that case we should probably have the information in the manual its self (glossary can be kept short, and link to a manual page). ---- *re: external links:* I don't see why not? But don't think we need more than 1-2 ... per term, if any.

gandalf3 self-assigned this 2015-08-31 20:34:47 +02:00

gandalf3 commented

2015-08-31 20:34:47 +02:00

Claiming to edit description

gandalf3 removed their assignment 2015-08-31 21:16:57 +02:00

gandalf3 commented

2015-08-31 21:16:57 +02:00

I've updated the description with more guidelines. If it looks good, I can start writing a section for this in the main style guide on the manual.

Campbell Barton commented

2015-09-01 09:43:04 +02:00

Committed most of the text you're written to our style-guide, see

https://www.blender.org/manual/about/writing_style_guide.html#glossary

The one thing I left out is the linking part, infact I dont really have a strong opinion on this and your proposal seems fine.

But think its not necessary to document everything., Otherwise, we end up with a wall of text which is off putting,

I think with these kinds of details, can be followed from reading existing entries.

Committed **most** of the text you're written to our style-guide, see https://www.blender.org/manual/about/writing_style_guide.html#glossary ---- The one thing I left out is the linking part, infact I dont really have a strong opinion on this and your proposal seems fine. But think its not necessary to document **everything.**, Otherwise, we end up with a *wall of text* which is off putting, I think with these kinds of details, can be followed from reading existing entries.

Campbell Barton commented

2015-09-01 10:17:32 +02:00

Note, I've committed URL formatting: rBM574

See also Some URL on Wikipedia.

RST has a .. seealso:: directive, but it adds a textbox which is a bit heavy (draws too much attention) in this context IMHO.

Note, I've committed URL formatting: rBM574 > See also **Some URL** on Wikipedia. RST has a `.. seealso::` directive, but it adds a textbox which is a bit heavy (draws too much attention) in this context IMHO.

Campbell Barton commented

2015-09-01 10:27:24 +02:00

Changed status from 'Open' to: 'Resolved'

Campbell Barton closed this issue

2015-09-01 10:27:24 +02:00

Campbell Barton self-assigned this 2015-09-01 10:27:24 +02:00

Campbell Barton commented

2015-09-01 10:27:24 +02:00

Added URL reference, as a bullet-point, instead of a before/after example (takes less room) rBM575.

Since this has been committed into the manual, I'm closing this as resolved.
Minor tweaks can be made to the glossary doc if we really need.

Added URL reference, as a bullet-point, instead of a before/after example (takes less room) rBM575. Since this has been committed into the manual, I'm closing this as resolved. Minor tweaks can be made to the glossary doc if we really need.

gandalf3 commented

2015-09-01 21:42:41 +02:00

Great! Thanks!

After starting to go through more of the glossary I found a few instances of numerical characters used in the middle of a sentence:

Color Blend Modes
Ways in which 2 colors can be blended in computer graphics.

IMO it would be preferable to write it out as "two" in such cases.
If it's agreed that this is suboptimal, I can include these in my list of problem entries.
Not sure if this needs to be mentioned in the style guide though (perhaps it can be assumed)?

Great! Thanks! After starting to go through more of the glossary I found a few instances of numerical characters used in the middle of a sentence: >**Color Blend Modes** >Ways in which 2 colors can be blended in computer graphics. IMO it would be preferable to write it out as "two" in such cases. If it's agreed that this is suboptimal, I can include these in my list of problem entries. Not sure if this needs to be mentioned in the style guide though (perhaps it can be assumed)?

Campbell Barton commented

2015-09-02 05:28:54 +02:00

@gandalf3, seems fine (committed rBM576.), though this is more general writing style stuff, (not just glossary).

Though this is one of those things I think we could leave out from the writing style doc.
Authors can just make sure writing style is reasonable when it comes to details like this.

@gandalf3, seems fine (committed rBM576.), though this is more general writing style stuff, (not just glossary). Though this is one of those things I think we could leave out from the writing style doc. Authors can just make sure writing style is reasonable when it comes to details like this.

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Define a consistent writing style for glossary entries #45893