--- title: "Voice" canonical: "https://documentation.chaos.com/space/DOCSGUIDE/113290889/Voice" format: markdown --- ` ` ## **Active Voice** --- **All text should be written in active voice. Do not use "you" or "we". Make the software the actor. **   | | | | | --- | --- | --- | | **Wrong ** | **Why wrong ** | **Right ** | | You can set the color of an object with a material. | use of "you" | A material can set the color of an object. | | A material can be used to set an object's color. | passive | |   ### Page (Section) Explanations    Every page needs an explanation or introduction about why this page is there. Section pages should include explanatory paragraphs whenever possible.  ### Language for Parameter Definitions   No need to start the definition with "This is.." Just state what it is.  > Macro (ui-text-box) > > Use present tense. > > "The value V-Ray uses..." > > NOT "The value V-Ray will use..." Avoid the use of future tenses! Remember that conditional clauses can be used with present tense.   On sentences, it is okay to start with "The" for gentler readability. If the definition is not a complete sentence, leave out "The".     More is better than less, as long as it makes things clearer.    **Phrases to avoid:** (you can usually just delete them): "allows you to..."   "when this option is selected..."  "enables the user to..."  > Macro (ui-text-box) > > It is a good idea to also avoid phrases such as "can", "might", "may", especially if you are explaining the behavior of V-Ray. It literally means you don't know or you are unsure of what the program is doing. Complete sentences are easier for users to read, so use them unless the definition really is very short.  Try to use precise language. The word "use" is not as precise as "applies", "retrieves", etc.  Where a parameter requires a detailed explanation, start with  the definition itself, and then explain it.  Consider the questions a user might have about this parameter, especially for complex processes, vague parameters, and unusual parameter names. What does the number value mean, exactly? Why is this parameter even there? Look at it from the user's perspective, not the program's.  If large/small values are mentioned, give a clue as to what is considered large or small.   Recommendations on using the parameter should be placed separately below the definition as a note.  **Examples of parameter definitions**:   **Wrong**:  Back material - this is the material V-Ray will use for back side faces. The back side is determined by normals  Medium Color - the color for the medium scattering layer.  Flake map size - internally the material creates several bitmaps to store the generated flakes. This parameter determines the size of the bitmaps. Lower values reduce RAM usage, but may produce noticeable tiling in the flake structure. Higher values require more RAM, but tiling is reduced. Be careful when using the Directional filtering method, as it may quickly take up gigabytes of RAM for larger map sizes.  Base Material - allows you to select the base material to which the bump/normal effect will be added.   Global max depth - enables the user to globally limit the reflection/refraction depth. When this is unchecked, the depth is controlled locally by the materials. When this option is checked, all materials use the Max depth specified here.   **Right**:  Back material — The material applied to "back side" faces. V-Ray uses surface normals to determine which faces are pointing to the "back".   Medium Color - Color for medium scattering layer.  Flake map size - Size of bitmaps used to store the generated flakes. Internally,  the material creates several bitmaps to store the generated flakes, and this parameter determines the size of the bitmaps. For example, a value of 512 generates several 512x512 bitmaps. Lower values reduce RAM usage, but might produce noticeable tiling in the flake structure. Higher values require more RAM, but tiling is reduced.   Note: If using the Directional filtering method, large values (over 2048) can quickly cause the bitmaps to take up gigabytes of RAM.  Base Material - The base material to which the bump/normal effect is added. The bump effect is layered on top of this material.  Hidden lights - Determines whether or not lights marked as hidden in your 3D software application will be used by V-Ray.    Always - Hidden lights are always used by V-Ray regardless of whether it is rendering or creating a .vrscene file.   Never - when this option is selected hidden lights will never be exported to V-Ray even though during animation certain objects may become visible.   Auto - when this option is selected lights with animated visibility will be exported to V-Ray only when they are visible.  Global max depth - Globally limits the reflection/refraction depth. When this option is disabled, the depth is controlled by local materials. When this option is enabled, all materials use the Max depth value.