Practical Tips

In this article

If you are translating - help checking the original text. For new contents - keep in mind what your text needs to convey, how it will help users. Also see the Writing New Content page.

Product and company name

Never just call our product Banana, but always Banana Accounting. Never just call our company Banana, but Banana.ch SA

Use an active voice instead o a passive one

In active voices the subject is the one making the action. Whenever possible use active voice in your texts.
Example:
NO: A new accounting file has been created by Marc
YES: Marc created a new accounting file

Capitalization

  • email addresses and websites are never capitalized: info@banana.ch - www.banana.ch
  • Never randomly capitalize words in the middle of a sentence. HSome words are never capitalized, others always are. Here is a list of words and how we should write them: Words List
  • The names of parts of the program are always capitalized, NEVER their role.
    Example:
    NO: go to the Transactions Table.
    YES: go the the Transactions table.
    Also note how the programs parts and program's commands are in bold.

Titles style

Case Title - in this style the first character of each word is capitalized (except for conjunctions and articles). Example: Snow White and the Seven Dwarfs This style is usually used in News titles or Posts

Sentence Case - in this style only the first letter of each sentence + proper nouns are capitalized. For example: Snow White and the seven dwarfs. This style is usually used in all our online Documentation.

Title styles are used ONLY IN ENGLISH - in other languages we only use Sentence Case.

Don't use Bold style for titles on our website - use instead the Drupal styles Title 1, 2, 3 and 4. If you stumble on old pages where titles are still in bold, take it off.

Numbers

As a general rule, if numbers are at the beginning of the sentence use the word, otherwise the number.
Example: Ten dogs and 8 cats.

Amounts - for all amounts, mark thousands with an apostrophe "'", and decimal with a stop sign "."
Example: 10'980.50

Currencies - always put currency symbol before the amount and use the 3 letter symbol.
Example: EUR and not € - USD and not $

Percentages - Use the % sysmbol instead of writing ... "per cent".

Bulleted or numbered lists

Pay attention that all the lists have the same punctuation:

  • Decide if there is a stop sign at the and, and if so, put it everywhere.
  • If there is a list of brief texts, DON'T put a stop sign at the end. If there are long sentences or paragraphs then yes.
  • Always capitalize the first letter o each bulleted list.

Exclamation points (!)

Use them sparingly and not more than one at a time. Too many don't look good. Only use them in a positive context, never for error messages or alerts.

Quotation marks

Banana commands or names need to be in bold and not using quotation marks. Use quotes only to quote someone else's phrase.

Semicolons

Use them sparingly. If you feel you need to use it, your sentence is probably too long.

Paths

When you need to indicate a series of steps you can set up a path using the right arrow symbol →
Example: File menu → File Properties command → Options tab → Previous year file.
Please note that the programs commands are in bold, where the arrow is not.

Italics

Italics style is very rarely used, mostly to indicate magazines titles or texts.
Example: The Newsweek magazine published an interesting article.

Web Elements

Alt text

Alt text is a way to label images, and it's especially important for people who can’t see the images on our website. Alt text should describe the image in a brief sentence or two.

Example of alternate texts in images

Buttons

Buttons should always contain actions. The language should be clear and concise. Capitalize every word, including articles.

Standard website buttons include:

  • Try for free
  • Buy Now
  • Subscribe
  • Email Us

Checkboxes

Use Sentence case for checkboxes.

Forms

Form titles should clearly and quickly explain the purpose of the form. Use title case for form titles and sentence case for form fields. Keep forms as short as possible. Only request information that we need and intend to use.

Headings and subheadings

Headings and subheadings organize content for readers.
Don't use Bold style for titles on our website - use instead the Drupal styles Title 1, 2, 3 and 4.
Headings (H1) tell people what they’re about to read. Use them for page and blog titles.
Subheadings (H2, H3, etc.) break articles into smaller, more specific sections.
Headings and subheadings should be organized in a hierarchy, with heading first, followed by subheadings in order.
Include the most relevant keywords in your headings and subheadings, and make sure you cover the main point of the content.

Links

Provide a link whenever you’re referring to something on an external website. Use links to point users to relevant content and trusted external resources. Don’t include preceding articles (a, an, the, our) when you link text.
Example:
NO: Read the automation guide for details.
YES: Read the automation guide for details.

If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.

Links are like road signs - always indicate the destination!

Don’t say things like “Click here!” or “Click for more information” or “Read this.”
Write the sentence as you normally would, and link relevant keywords.
Example:
NO: More information
YES: How to start a Cash Book right away

Lists

Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Use number lists when the order is important, like when you’re describing steps of a process. If list’s order doesn’t matter choose bullet lists.

If one of the list items is a complete sentence, use proper punctuation and capitalization on all of the items. If list items are not complete sentences, don’t use punctuation, but do capitalize the first word of each item.

Related articles

Sometimes a long piece of copy lends itself to a list of related links at the end. Don’t go overboard—4 is usually plenty.
Related articles should appear in a logical order. Avoid repeating links from the body text in related articles.

SEO (= Search Engine Optimization)

  • Organize your page around one topic. Use clear, descriptive terms in titles and headings that relate to the topic at hand.
  • Use descriptive headings to structure your page and highlight important information.
  • Give every image descriptive Alt text.

 

Share this article: Twitter | Facebook | LinkedIn | Email