Editorial Style Guide v1.0.5
Contents
1. e Stick to the principles of using Plain English outlined in this document When you are talking to your User say exactly what you mean using the simplest words that fit This does not necessarily mean only using simple words just words that the User will understand Make use of the Glossary as a reference point for definitions of common and not So common words in use in the Community In the subject matter we are dealing with technical jargon is the standard and it is our responsibility to ensure that we demystify it for the whole Community You can use jargon when writing for people who will understand the terms and phrases it can be a useful form of shorthand However try to avoid using specialist technical jargon in general and when it is necessary explain the meaning of the terms used So in general keep to everyday English whenever possible Again imagine talking to your reader across a table Do Not Be Afraid to Give Instructions e Stop e Click the XYZ icon e Please refer to the ABC forum These are all commands officially called imperatives They are the fastest and most direct way of giving someone instructions We could write these commands in a more expansive form but this is often unnecessary to achieve the correct result e The User should be told to Stop e You should click the XYZ icon e We would be grateful if you would refer to the ABC forum There always seems to be a fear of commands The most c2. and bottom rather than the top middle and bottom long sentences joined by conjunctions long sentences with confusing subordinate clauses incomplete sentences that leave out the articles over elaborate sentence structure and syntax unnecessary adjectives in a phrase that could stand alone without them unnecessary adverbs in a phrase that could stand alone without them use of semi colons use of the colon e do not be use to introduce a figure table heading or at the end of a procedure introduction e always use to introduce a list or before an explanation do not use double spacing use an ellipsis to show that you have omitted something from a sentence or to indicate a pause when you quote displayed text do not have a space before the ellipsis Rules It is not the intention to rebel against the grammatical rules in the aim of achieving good User documentation There are mysteries and preconceptions surrounding grammar that often impede the writing of user friendly documents You can start a sentence with and but because so or however You can split your infinitives So you can say to boldly go You can end a sentence with a preposition In fact it is something we should stand up for And you can use the same word twice in a sentence if you can t find a better word Of course this does not mean you should break these so called rules all the time just when they make a sentence flow better Summary S
3. correct image for the screen that is the subject of the Help Screen Sections e Identify the correct sections that you should retain or add to the basic template format Delete those that are unnecessary e Consider the section title and what this represents and add content to each section in turn as required e Do not duplicate content that is contained within the support group of pages Toolbar Mini icons Common Headers Details Parameters Sources e Do not simply copy the words of another source outside of the Joomla Help Sites own content The processes which you are reviewing are not copyrighted the way in which others have written about them probably is This includes the Forums Use these resources to ensure you understand a process properly and then put it into your own words e fyou must include copyrighted material ensure that you properly index and reference it as such This includes images Review Once you feel a document is complete it is important to review it and determine whether e what you have written actually explain what you intended originally e the processes described work e itis complete e the formatting is correct e the rules of this guide the Visual Style Guide and the Document Process Guide have been correctly implemented If you consider all is complete then you need to indicate this to be the final version of the document and it is ready to be moved to the next stage See the Doc
4. words Capitalise the words Front Page when referring to the Menu Item element of Joomla content Spell with one in the middle and one at the end One word not two Spell with au in the middle Begin with grate Single T at the end Spell with a single r and a double s Two words No hyphenation One word No hyphenation Always two words Always capitalise except in code or when a file extension Begin with hypo and end with isy Spell with a double m End with ent rather than ant Spell with one End with erary One word but with the J and S capitalised Always capitalise and include the exclamation mark every time except in code Use as the starting point to all references to directories within the core installation to avoid confusion with the web server or database root One word not two Use licence as a noun for the permit you obtain to Accepted Word login logon logoff and logout log in log on and log off log out maintenance Mambot Manager manoeuvre Media Manager Menu Menu Item metadata millennium minuscule misspell Module multitasking MySQL News Feed Manager necessary and necessity occasion OK Unacceptable Word maintainence mambot manager maneuver media manager menu menu item meta data mispell module multi tasking multi tasking mysql MYSQL newsfeed Newsfeed neccessary occassion Ok ok Detail do so
5. BR Joomla because open source matters Editorial Style Guide Joomla User Documentation Team Version 1 0 5 19 June 2007 Andy Wallace Acknowledgements amp License License This document is released under the Creative Commons Attribution NonCommercial ShareAlike 3 0 Unported license Acknowledgements would like to pass on my thanks to the following members of the User Documentation Team for their efforts of proof reading and ideas on this document Chad McKissick Leandro Berganti os Brian Lieske Thanks Andy Wallace Change Log Table of Contents Whatitis All ABOUT PL 5 The MISSION Statement ene cette ets onera aa ed ede aduer an AEN Re ce RR 5 miel e 5 The Essentials E 5 How to Use the Editorial Style Guide ESG ssssssse ee 6 General Guidelines for Joomla Documenters ccececcceeeeeeeeeeneeeeeeeeeeeceeeaeceeeeeeesecenaeeeeess 7 Understand your Audience tier redeo boc idet Rte den i Rn n e ERR NE 7 General Principles of Documenting Joomla 8 Using Plain English in Joomla User Documentation 9 What Do We Mean by Plain English 9 What is the Intention of Using Plain English em 9 Keep Your Sentences Short ctt anne tenants tent in PLAN ERE EN gx eV ER eq Rug RA 9 Use Active Verbs MM 10 Proper Use of Passives sssssssssssssssessesseseeenen eren ener eren nennen EnEn EnEn 11 Use of Yo
6. cript practice and practise presence privilege proofread questionnaire really receive recommend and recommendation restaurant rhythm secretary Section Unacceptable Word ommission on line on line open source over write over write pass word php poll manager posess Post Script post script presance privilage privildge proof read proofed proof read questionare realy recieve reccomend restorant restaront writhm secratary secretery section Detail Spell with one m and a double s One word Capitalise the O and S Spell with an i before and after the g One word One word Always capitalise except when used as a file extension or in code Always capitalise when referring to the Component in Joomla One word always capitalise when referring to the Extension Spell with a double s before and after the e One word Capitalise P and S Use practice as a noun when describing actually doing something rather than just discussing it or theories about it as in put your good manners into practice Use practise as the verb improving your skill by doing something over and over End with ence Spell with ege at the end This applies to all derivatives as well such as proofreader proofreading etc Spell with a double n and end with aire Spell with a double in the middle Use i before e except after c Spell with a single c and a double m Spell
7. den ette rated ee eene Eg Lene nee ket V ea see roa vena Rede 23 Help Screen SPSCIICS sance cu etre ener a Te SERRE ER Lene nete e e deo nee RNE rat tetes a 24 HT EA 24 Header Blok laits 24 SOCON S ecce see tete rede ester ea nee kr EE RARE EXE CET set e eL E eee Rd eure eee ER uen 24 SOUCO fme 24 MO P 24 General Guidelines for Proofreaders and Editors ssssssssssssssssesse 25 Procedure for Proofreading and Editing sssssee en 25 Marking Corrections from Proofreading sese eme 25 Appendice comm e wheadanshasdbauabsiddanaed aa a ta a e i a 26 General Style Guides for Reference se 26 Life Rror ioo tm 27 Words to Wath anini sn ends ete Dh o beu ene a hate a reddas dede 28 What it is All About The Mission Statement The Joomla User Documentation Project has the aim of providing documentation to the Users and Administrators of a Joomla CMS with clear concise useful and usable information for the Front end and Back end functionality available to them To make Joomla the best documented Open Source Project Purpose The User Documentation Team UDT Editorial Style Guide ESG is the official reference guide for Joomla User Documentation that is available within the Joomla Help Site There are slight variations with regard the di
8. e UDT Documentation Project is and will always remain to be the provision of technically accurate information for the Users of Joomla To this end we will always strive to ensure the same accurate information is borne across all of our documentation How to Use the Editorial Style Guide ESG There are a number of ways to use the ESG to assist in the writing proofreading editing and production of Joomla documentation Read the entire guide to familiarise yourself with the standards and editorial style issues specific to Joomla User Documentation This is essential if you wish to contribute to the project If you are new to writing this type of material or simply just as a refresher you may like to check out the additional resources we reference throughout the guides These will help you become familiar with general technical writing skills as well as documentation processing in general As an ongoing desktop reference guide as to how to handle specific issues or words that will arise in the normal course of preparing documentation for the project As a source document for Third Party Extension documenters who want to provide their documentation with a similar look and feel to official Joomla documentation As a resource for Developers to assist them in the writing of tooltips and other written elements within the software code that in turn makes the visible display of Joomla more user friendly and accessible Use it in conj
9. e of Technical Content Help Screens Minimum User Manual Installation Manual Administrator Manual FAQ s Template Manual Developer Manual Maximum General Principles of Documenting Joomla Whatever process you happen to be writing about it is essential that you try out the actual process whilst writing that you write the content in the correct sequence and that your explanation works Ensure you are using the most recent version of Joomla at all times Whenever possible keep sentences simple one idea per sentence Sentences should be generally no more than 25 words in length Use plain English whenever possible remember Translation Partners translate much of the documentation we produce into many other languages avoid the use of complex English phrases or colloquialisms Use common words whenever possible Whenever possible limit the explanation of each procedural step to one action using 25 words or less Provide instructions using the active tense rather than the passive tense For example write explanations using task oriented action verbs There may be exceptions to this and many of the other rules so if you are uncertain double check with another Author or Editor regarding such situations Avoid the use of vague language unexplained technical terms references and any other unexplained or out of context content Do not use ambiguous statements personal opinion or any other content that d
10. etracts from the clarity of the subject matter Fully explain technical references where these are included If necessary refer to a developer for clarification Make your writing more direct by removing any unnecessary wordiness and stressing what is most important within the statement Imagine you are discussing the topic with the User across a table If it does not sound the same as it would in this context then it probably needs revising Using Plain English in Joomla User Documentation Throughout this document you will see reference to the User In the context of this and all UDT documentation this relates to the Front end User as well as the Back end Administrator What Do We Mean by Plain English Plain English does not mean writing in a simplistic or a child like manner Nor does it mean reducing the length of a document or changing the meaning or emphasis of the message it contains just for the sake of it It is not as easy as some would have you believe to write documentation It is all too easy to over complicate the message we are trying to give to the Users Clear concise documentation does take time to produce it does get easier with practice and support but there is not a quick fix here either We need to establish a method of writing that is efficient and user friendly By using plain English our aim is to make our documentation e faster to write e easier and faster to read e get the message across t
11. fferent individual documentation types such as Help Screens User Manual Administration Manual Installation Manual and Supported Documentation but the essentials are the same throughout the project We will release separate documents advising on document specific requirements when necessary Read and use this guide in conjunction with the Visual Style Guide VSG and Documentation Process Guide DPG Our intention in releasing these notes together with the individual process references is to guide you through the requirements and standards that we are looking to inject into Joomla documentation The Essentials Clarity We want to reduce the use of technical jargon in non development documentation or when this is necessary to provide an effective explanation of precisely what the referenced items actually mean Consistency We want to standardise the written material so that all Official Joomla Documentation and Supported Documentation maintains a consistent style and tone Correctness We want to produce high quality User documentation that is devoid of spelling grammar punctuation and word usage errors Consideration We want to make the content accessible and understandable to all people including those from different parts of the world where English is not their native language those with disabilities and people from various backgrounds and cultures Technical Correctness and Consistency One of the key priorities of th
12. first letter Spell with icle at the end Capitalise except when using to refer to a spiders trap Two words unhyphenated Capitalise the words when discussing the Component variant Web Link Manager As the World Wide Web is a proper noun we use initial upper case letter in the same way as you do with your surname This is a change Site Accepted Word weird wilful withhold World Wide Web WWW Unacceptable Word wierd willfull willful withold Worldwide Web Detail however is lower case Spell with the e before the i Only use a single in the middle and one at the end Spell with a double h in the middle Capitalise as it is a proper noun Three separate words Capitalise the abbreviation except in URL s
13. gh the material again and fine tune it where needed Reading out aloud often helps you to identify problems that you missed when reading silently Check for common mistakes such as not completing parentheses brackets and quotation marks comma splices dangling modifiers and commonly misspelled words see Words2Watch Another suggestion to help you identify errors especially in spelling is to proofread the document in reverse from bottom to top and right to left Constantly check compliance with the Visual Style Guide and Documentation Process Guide Marking Corrections from Proofreading Copy the text that the comments apply to into the Comment facility Then record your corrections comments and suggestions Please follow these directions Please use green text for all additions and modifications and red for any text that the author should delete or replace In other words if you are e Adding extra new text use green text e Deleting unnecessary text use red text e Replacing existing text use red for the text to be deleted and green for the new text to be added e Modifying existing text use green text for example correcting a spelling error Post any questions comments or suggestions you may have to the Suggestions Appendices General Style Guides for Reference We aim to create all Joomla documentation using British English en_GB as the base language It is done in this way to ensure there is a sing
14. hris completed the review Passive The latest version was released by the Joomla Active Joomla released the latest version Using passive verbs can cause several problems e they will often be confusing e they can make writing more longwinded and e they make writing less lively Proper Use of Passives There are appropriate occasions when you can use a passive verb e To prevent something sounding hostile The formatting of the text needs doing passive is better in most circumstances than You have not formatted the text active e To avoid taking the blame as if we would Mistakes have been made passive rather than We made mistakes active e When you do not know who or what the doer is The User Documentation Team has been selected e If it simply sounds better Yes there will be occasions where this applies You should aim to make about 80 to 90 of your verbs active Use of You And We In Documentation Our readership is likely to be the new User to Joomla and probably someone with little or no technical skills either as far as their understanding of coding and other issues We can make the documentation more User friendly by referring to the reader as you Whilst this may not be what people authors are used to doing this approach may just help the User settle in a bit more easily Here are some examples of this e Community members must send us e You must send u
15. it would also look very strange written as Joomla version one point five If we were to say There have been 2 major releases of Joomla this would be inappropriate and we should in fact say There have been two major releases of Joomla Do not use Numerals to start a sentence Either write the number out in words or preferably use a different order of words so that the number occurs within the body of the sentence If your text includes fractions do not use any editor specific characters as are found in most word processor programs Enter the fraction as 8 1 2 eight and a half ensure there is a hyphen between the whole number and the fraction However it is unlikely that you will need to use fractions in Joomla documentation and you should endeavour to convert any that are required into decimals instead Use Lists Where Appropriate The Visual Style Guide explains the formatting of lists in detail Lists are excellent for splitting information up and adding emphasis Horizontal Inline List There are three main types of list for us to consider here 1 the horizontal inline list 2 the vertical numbered list 3 the vertical bulleted list Use horizontal inline lists when you need to define a list of items but emphasis is less important Limit the number of items to four or five otherwise consider using a vertical list Vertical Numbered List There are three main types of list for us to consider here 1 the hor
16. italise the word Banner when referring to the element of the Joomla Banner Component One word not hyphenated or two words Accepted Word business Category Manager command Contact Manager checkbox check in noun adjective Global Check in Component Manager consensus and consensual Contact Control Panel controversy CSS database desperate dial up disappoint and disappointment eighth e mail Extension s embarrass Unacceptable Word bisiness comand check box checkin noun adjective concensus control panel contraversy CSS data base desparate dialup dial up dissapoint disapoint dissappoint eigth E mail email extension s embbaras Detail Spell with busi at the beginning Capitalise the word Category when referring to the element of Joomla content Always capitalise when referring to the Component element or Manager function We will be using check in which must be capitalised when referring to a specific function Menu Item or button such as Global Check in It is correct to use check in verb as in check in your materials Capitalise the word Component when referring to an Extension in Joomla Spell with sen in the middle Capitalise the word Contact when referring to the element of the Joomla Contact Component Capitalise when referring to the Joomla Back end functional area Always capitalise except in code or
17. ite the information or need to research the topic Do you need additional support Finally based on the answers to the previous questions Plan a sequence and structure to the element you are writing about Consider what others have written and try to follow a similar structure assuming that it is correct This is a personal interpretation issue so discuss with others if necessary Identify whether there is already existing documentation within the Help Site Workshop that fits the bill and you can reuse it there is no point reinventing the wheel every time Establish a cut off point at which to stop writing about the topic to avoid overdoing it Where this point is depends on the context of the document This may all seem a lot to be thinking about but it will quickly become an automatic part of your writing procedure Help Screen Specifics The following are general guidelines for each of the elements of the Help Screens Title e Edit the title so that it duplicates the title of the Help Screen Header Block e The content of the Header Block is pre established by need e Edit the block for the Help Screen currently being written or edited e Add external references for Further Information locations e Check that all links do what we intend this includes URL s anchors links within the current document and links to other Help Screens of direct relation that are not referenced within the main body of the text e Add the
18. izontal inline list 2 the vertical numbered list 3 the vertical bulleted list Only use vertical numbered lists when you are describing a defined process that must follow a set sequence or when you need to refer to the points within it from the surrounding text Limit the number of items to around seven to ten otherwise consider grouping related items under sub lists Vertical Bulleted List There are three main types of list for us to consider here e the horizontal inline list e the vertical numbered list e the vertical bulleted list Use bulleted lists whenever you need a list of items to be emphasised outside of the main text Limit the number of items to around seven to ten otherwise consider grouping related items under sub lists Bulleted and numbered lists must always have an introductory statement Use lowercase letters to start the listed points except when they are complete sentences when they must start with a capital letter and end with a full stop period With a list that is part of a continuous sentence put semicolons after each point and start each with a lowercase letter If you know that e you have an Apache server e you installed MySQL and e you installed PHP you should be able to install Joomla As you can see the next to last point has and after the semicolon If you only had to prove one of the three points instead of all of them this word would be or Always make sure each poi
19. le language variant that it is necessary to understand making it easier for Translation Partners and others to translate the documentation available within the Joomla core and the Help Site You can research much of what we aim to achieve by way of style grammar punctuation and general word usage in many of the available online style guides and web sites The following is a list in no particular order of preference of just a few of such sites e http Awww usingenglish com Those writers and contributors whose first language is not English will find this site most beneficial e http en wikipedia org wiki Style_guide International standards This page on the popular Wikipedia web site gives access to a whole raft of other resources far too many to be listed here with any real meaning e http economist com research styleGuide The Economist Style Guide is a representation from a book handed to all new reporters on The Economist business journal e http www askoxford com view uk AskOxford com is the online presence of the Oxford University Press the publishers behind many language orientated books including the Oxford English Dictionary e Spelling differences between American and British English e The American British British American Dictionary e WWlib Notes on American English e It is very easy to be caught up in the detail of these sites and lose to direction with regard the documentation itself so we will try
20. mething like hunt or drive but use license when you mean it as a verb to give permission to or allow someone to do something or for something to occur Noun always one word one g the act of logging into or out of a computer or Web site Verb to go through the procedure of logging in to or out of a Web site for example Spell with ten in the middle and end with ance Always capitalise when used for a Joomla Extension Remember from 1 5 this is replaced by Plugin When referring to either the User level or a Manager screen Poll Manager it is capitalised Spell with oeu in the middle and vre at end Capitalise when referring to the Joomla function When referring to a specific menu in Joomla always capitalise Two words and capitalise both when referring to the specific element within Joomla but not when generally discussing any old menu items One word Spell with a double and a double n Spell with a u after the n Spell with a double s Always capitalise when used for a Joomla Extension one word Always capitalise when referring to the Component within Joomla and always two words Manager when included is always capitalised Spelled with one c and a double s Spell with a double c and a single s capitalise both letters Accepted Word omission online Open Source OS original overwrite password PHP Poll Manager platform Plugin s possess and possession PostS
21. nt follows logically and grammatically from the introduction For example if you took out you from the second and third points it would still flow as a normal sentence but not as a list The third point would then read If you know that installed PHP which obviously does not make sense Correctness of Spelling Punctuation Usage and Grammar It is essential to maintain correctness in spelling punctuation word usage and grammar when producing documentation both for online and offline use Spelling and Usage Remember to use the British English en_GB spelling of words rather than the American English spelling Be on the lookout for words that are often spelled incorrectly Words to Watch Check for and correct the following issues e Inconsistent capitalisation e Inconsistent use of terminology e Repeated words e Typographical errors e Missing words e Verbs in the wrong tense e Emotions desires opinions sense of location or dimension to an inanimate object anthropomorphism e The used to begin article titles manual titles chapter titles headings figure captions table captions and callouts e Contractions don t wouldn t isn t although these are acceptable where they assist in making the document more readable Grammar and Punctuation Keep an eye out for and correct these common errors in grammar and punctuation use of a slash as well as using and or inconsistent use of hyphens and dashe
22. o the User that Joomla is as easy to use as we claim it to be and exactly how to do this but that it does require some effort on their part So it s vital that we get it right as often as we possibly can What is the Intention of Using Plain English Our aim is to create our documentation written with the end User in mind and with the right tone of voice which is clear and concise To create documentation that is straightforward for the Translation Partners and others to convert to their own language Keep Your Sentences Short The literary world generally accepts that an average sentence length of 15 to 25 words is about correct This does not mean you have to make every sentence the same length Be dynamic Vary your writing by using a mix of short sentences like the last one with longer ones like this one Follow the basic principle of only having one main topic in a sentence plus perhaps one other related point You will soon quite easily develop the ability to keep to the average sentence length However at first you may still find yourself writing the odd long sentence especially when trying to explain a complicated point but most long sentences can be broken up in some way Use Active Verbs We want our documents to sound active precise and user friendly not passive confusing and overly technical Generally there are three main components to a sentence e a subject the person group or thing doing the acti
23. ommon fault is putting Users should do this or you should do this instead of just do this Perhaps we worry that commands sound too harsh Here are some examples of longwinded phrases and shorter versions that use commands e You should just think of it as a complete statement e Just think of it as a complete statement e Writers should aim to be punchy e Be punchy e The topics should be split where necessary e Split the topics where necessary The last example is probably the worst because it uses a passive verb should be split Unfortunately this is very common in instructions For example e The program should be uncompressed from the zip file The contents should then be uploaded to the web site e Uncompress the program from the zip file Then upload the contents to the web site Avoid Nominalisations A nominalisation is a type of abstract noun or in other words the name of something that is not a physical object but a process technique or emotion Nominalisations are formed from verbs For example Verb Nominalisation complete completion introduce introduction provide provision fail failure arrange arrangement investigate investigation So what is wrong with them The problem is their use instead of the verbs they come from Moreover because they are merely the names of things they sound as if nothing is actually happening in the sentence Like passive ve
24. on e averb the action itself and e an object the person group or thing that the action is done to In the following sentence Chad played on the computer e the subject is Chad he is doing the playing e the verb is played it is the action and e the object is the computer it is being played Whilst this is a very simple sentence there will generally be a few more words as well Chad a Joomla User from the USA played on his computer every night after work However the subject verb and object are still there and their order indicates that this is in fact an active verb Reverse these three elements and the sentence becomes passive e object then verb then subject The computer object was played verb on by Chad subject Played has become a passive verb here The sentence says what is being played before it says who is doing the playing You will see that in making the sentence passive we have introduced the words was and by and the sentence has become clumsier The subject does not always need to be a person and the object is not always a thing The computer game beat Leandro is active but Leandro was beaten by the computer game is passive Here are some more examples of how to turn a passive verb into an active verb Passive The Help Screens will be completed by us soon Active We will complete the Help Screens soon Passive The review was completed by Chris Active C
25. rbs too many of them can make the reading of your text hard work Here are some examples We had a discussion about the matter We discussed the matter There will be a release of the latest version of Joomla by the Developers The Developers will release the latest version of Joomla The implementation of the method has been done by the UDT The UDT has implemented the method Use Positive Language Always try to emphasise the positive side of things except when it is necessary for you to be actively negative For example e f you do not send your payment your subscription to the Magazine will lapse Negative e Please send your payment so that we can ensure you receive the next issue of the Magazine Positive Date Time Measurement and All Date Format Dates will always be listed day as a numeric month name in full and the year as a four digit numeric without any ordinals th rd st or punctuation as in the following example 12 June 2007 Time Format Joomla uses the International Standard Notation for time code for the time format in its documentation hh mm ss For example 23 59 59 represents the time one second before midnight Time Zones All time zone references should be referenced against Coordinated Universal Time UTC also known as Greenwich Mean Time GMT or Z zulu A time zone is shown relative to UTC and is displayed as UTC hh mm For example UTC 01 00 means one ho
26. s e hyphens are used to prevent ambiguity with a numeral in a compound modifier with some standard prefixes and suffixes in spelled out fractions and in variable names of two or more words e do not use for industry accepted terms to construct verbs with an adverb ending in ly with numerals as single modifiers with a word that that uses a common prefix or with trademarked terms e to create an introductory piece of text use a paragraph break or a colon rather than an em dash or en dash inappropriate use of parentheses and brackets e use parentheses to contain the abbreviation of a term on the first occurrence of the full term e brackets should be used for optional command line entries but not as a substitute for parentheses or to indicate variables in text incorrect use of apostrophes e apostrophes used to denote plurals incorrect use of quotation marks e limit the use of quotation marks to identify quoted speech numbers letters or words referred to as such e donotuse single quote marks at all other than in direct representations of code terms must be legitimate or not used e ensure you define terms for the reader in the content itself or in the glossary incorrect use of comma splice e excess commas e commas used in a series of adjectives used as one modifier e commas between two short independent clauses e always use the third comma in a serial list for instance the top middle
27. s e Joomla will always tell Users before we e We will tell you before we e Further information is available from e You can get further information from It is acceptable to refer to the User Documentation Team and Joomla as we and there is nothing wrong with using we and I in the same document However do not use I on Official documents such as the Help Screens or Manuals Issues of Tone It is necessary to write the documentation in as consistent a manner as possible We will have contributors from different continents and cultures and whose first language may not in fact be British English with all its various nuances by setting a few basic guidelines and having a considered approach to these the result should be relatively consistent e Avoid making a personal statement or using your own opinion in Official documentation e Avoid humour This has the tendency to be territorial in nature and not everyone is going to understand that you mean something to be funny e Avoid using puns wordplay or innuendo to make a point e Avoid statements about future developments unless you are writing specifically about this The documentation must focus on what is and not what may be e Do not use colloquial language unnecessary jargon culture specific language gender specific language or condescension in the written tone Stick to the subject under consideration and write about the facts
28. tions or acronyms in a document as it can quickly become confusing Remember we are writing documentation for the User to read in comfort not an SMS message on a mobile phone Capitalisation Capitalisation is a method of emphasis refer directly to the Visual Style Guide for specific formats to use for the text we are writing Capitalise in the following situations All letters in acronyms unless the acronym is a well known exception the initial letter of the first word in a list item but only when the entry created is a full sentence the initial letter of a sentence the initial letter of a complete sentence after a colon to accurately replicate a key name on your keyboard such as the Shift key or Caps Lock key Capitalisation is an important issue with particular regard to proper names used within Joomla All the key components menus functions and more must be capitalised For example Modules Plugins Components Section Manager Site Menu Menu Item Article Use the exact capitalisation style of messages shown on the computer screen of hardware labels software titles and so on Use capital letters for names of people races cities regions counties states nations languages and other such proper names Use capital letters for titles of offices when the title precedes the name of an officeholder but not when the title occurs alone Use capital letters for the days of the week months special days and holida
29. to cover as many of these aspects as we can and add to these guides as we find necessary Primarily we use the Oxford English Dictionary as the reference for all spelling aspects Should you find a particular reference or issue that needs adding to these guides please notify the UDT on the forums at http forum joomla org index php board 62 0 html and we will look at your recommendation and include it if appropriate Words to avoid Try to use the alternatives we suggest in the table Word Alternative additional extra advise tell applicant you commence start complete fill in comply with keep to consequently so ensure make sure forward send in accordance with under keeping to in excess of more than in respect of for in the event of if on receipt when we you get on request if you ask particulars details per annum a year persons people prior to before purchase buy regarding about should you wish if you wish terminate end whilst while Words to Watch Words to Watch W2W are words commonly misspelled or which may have variations that depend on the Joomla style guide choices An entry which is just a word without a comment is to show how we are spelling that word If an entry has something rather than something else then it should be read as We are using the spelling of the first something rather than the other possible spellings sho
30. top and think before you start writing Make a note of the points you want to make in a logical order Use short words Long words will not impress your Users or help your writing style Use Plain English whenever possible Avoid jargon and colloquial words and explain any technical terms you have to use Keep your sentence length down to an average of 15 to 25 words Try to stick to one main idea in a sentence Use active verbs as much as possible Say we will do it rather than it will be done by us Be concise Imagine you are talking to your reader Write in a style that is suitable and with the right tone of voice Always check that your writing is clear helpful human and polite And always always make sure that what you have written works What to Document One of the key factors in writing a document is the question How do decide on what is appropriate to include in this Help Screen Manual reference There are questions that you must answer before this one What type of document are you writing for Who are you writing this document for e What is their anticipated level of experience with Joomla e What is their expected level of knowledge of supporting programs What should the target audience be able to get from the information am writing Will it add value to what already exists this one is more to do with proofreading and editing Then ask yourself Do you have the knowledge to wr
31. u And We In Documentation ss 11 Issues of Tone siennes 12 Do Not Be Afraid to Give Instructions ccccccceceeeeeeeeceeeeeeeeeeeeeaaeaeeeeeeeeeseceueaeeeeeeteneeees 13 Avoid Nominalisations ener nennen rnm nE inen nnn nenne 14 So what is wrong with them eene nnne nennen 14 Use Positive Language sienne 15 Date Time Measurement and All sssssssseeeeeeeneenn nennen nennen 16 Date Format sise 16 Time Format Eent 16 Blu PAe E 16 Seasons and Holidays 16 Units of Measurement seen 16 Abbreviations and Acronyms ss 16 Capital iSathon CE 17 Numbers versus Words 18 Use Lists Where Appropriate sis 19 Horizontal Inline List un ritenere E P iere secre edes 19 Vertical Numbered List 19 Vertical Bulleted List e ein eere ne aaa EEN aana NR REN NER ba ea tiennent 19 Correctness of Spelling Punctuation Usage and Grammar 20 Spelling and Usage 2 1 23e nie ares dis ARR Here antec ee ediaae coru 20 Grammar and Purict atlon onec ee rete ede cet nete ene Re een a Pc o nare pae Ea ERE ue vs 20 MUI X X els 22 PRUNES res X X 22 SUMIMANY E TE 22 What to Document e eere ee re
32. umentation Process Guide General Guidelines for Proofreaders and Editors w If you are simply proofreading a document identify your corrections comments and suggestions via the Comments facility in the Project Manager Do not edit the screen directly If you are carrying out a formal edit of the document make sure it is located at the correct stage of the overall process Make sure you have made a new copy of the document and that it has the correct version number Procedure for Proofreading and Editing The following are generally suggestions as everyone will have their own ideal way of completing the process Make several different passes through the material as you are proofreading in order to catch different types of issues each time through Avoid making any edits on the first pass just make a note of any obvious issues During the first pass look for obvious spelling punctuation grammar and usage issues that jump out at you right away You may want to review proper spelling punctuation grammar and usage rules before you begin so they are fresh in your mind as you are proofreading During the next pass carefully read and review the content for clarity consistency in style and tone and accessibility Ask yourself if the content makes sense if it is written in the best way it can be and if anything is missing that should be added Make sure you have caught everything that needs correction by passing throu
33. unction with the Visual Style Guide Use it in conjunction with the Document Process Guide Keep up to date with any changes that we announce in the UDT Forums General Guidelines for Joomla Documenters Understand your Audience The target audience of Joomla User Documentation has varying degrees of experience It is therefore difficult to present the content in a way that meets all of these levels all of the time The objective should be to write the content based upon who is most likely to be looking for information on a particular process or function and what level in their Joomla development they are likely to have reached For example Help Screens should primarily be aimed at new Users with little or no experience of Joomla nor in addition potentially little or no knowledge of the underlying components such as PHP MySQL Apache and associated software An Administrator Manual equally has to have a basic starting point but does not need to go over the basic functionality that a Help Screen or User manual has previously covered except when this is necessary as a prelude to a more detailed explanation Typically more material of a technical in nature will be contained in the Administrator Manual as a matter of necessity FAQ s Frequently Asked or Anticipated Questions span the full range of experience levels and technical knowledge and should be individually referenced to indicate the level at which they are targeted Scal
34. ur ahead of UTC Seasons and Holidays Always write seasons as spring summer autumn and winter Note the absence of a capital letter to start the word a common mistake It would be impossible to list all the national holidays of the world as a usable reference Deal with these on a case by case basis thereby avoiding creating a national or religious conflict Refer to a national holiday name followed by the country to which it refers in parenthesis Units of Measurement We will use the International System of Units SI for measurements Briefly this means the use of metre centimetre millimetre for distance dimensions length and width and grams kilograms and tonnes for mass weight For a detailed description of specific SI units please visit How Many A Dictionary of Units of Measurement a web site maintained by Russ Rowlett Abbreviations and Acronyms When using abbreviations and acronyms make sure that e when they are first introduced in a document you use the full term with the abbreviation or acronym following it in parenthesis e the next time the abbreviation or acronym appears in the same document you omit the spelled out term Find another way to communicate commonly misunderstood and misused abbreviations such as i e e g etc Consider replacing i e or e g with for example etc with and others or and more but these are only suggestions and it depends on the circumstances Avoid overusing abbrevia
35. when a file extension One word not two Spell desperate with per in the middle Include the hyphen between dial and up Remember to spell with one s and a double p Remember to use hth at the end E mail is obviously correct at the start of a sentence We will be going with e mail lower case and hyphenated for consistency Refer to Components Modules and Plugins collectively as Extensions Always capitalise when referring to CMPT s Spell with a single b double r and a double s Accepted Word extraordinary fascinate and fascination file name friend Front end Front Page front page fulfil gateway gauge grateful harass and harassment hard disk hardware home page HTML hypocrisy immediate and immediacy independent instalment itinerary JavaScript Joomla joomla_root keyboard licence and license Unacceptable Word extrordinary facination filename frontend Frontpage frontpage fulfill gate way gage gratful or graitful harrass and harrassment hard disk hard ware homepage HTM html hypocrasy hypocrisey imediate independant installment itinery javascript Java Script joomla Joomla key board Detail Do not omit the a of extra Spell with an s before the c Two words rather than one Spell with ie in the middle Ensure it is always capitalised and hyphenated when referring to the User public area of Joomla Always two
36. with au between the t and r Use an e after the r and end with ary Always capitalise when referring to the specific element within Joomla cms Accepted Word seize separate similar skilful skilfully skilfulness software source code style sheet subdirectory subdocument success and successful sufficient Super Administrator surprise tomorrow toolbar twelfth unfortunately until URL User vehicle Web Web link Web Link Web site Unacceptable Word sieze seperate simalar simillar similer skillfull soft ware soft ware sourcecode stylesheet style sheet sub directory sub directory sub document sub document sucess suficient super administrator tool bar tool bar twelth Url url user web weblink web link website Web Site web site Detail Spell with the e before the i Spell with par in the middle End with lar rather than ler Watch for variations as shown One word Two words Two words no hyphen One word One word Spell with a double c and a double s Use a double f in the middle and end with cient Always capitalise when referring to the Joomla User level Spell with an r before and after the p Spell with a single m and a double r One word Spell with an f in the middle Spell with ately at the end Use a single at the end Capitalise except when used in code When referring to a specific Joomla User always capitalise
37. wn in something else Accepted Word accessory accommodate administrator Administrator address aggression allege a lot alot amend and amendment apologize or apologise apparent argument Article AutoCorrect Back end backend backup and back up Banner bitmap bit map or bit map Unacceptable Word Detail Spell with a double c and a double s the ending is Ory Spell with a double c and a double m and ano before and after the m s Always capitalise when referring to the Joomla User level or the Back end Administrator Use of the latter should be limited to avoid confusion Refer to this area as the Control Panel when referring to the facilities and Back end when comparing to the Front end Spell with a double d Remember to spell with a double g and a double s Use a double and spell with ege at the end Use as two words not one Spell with a single m at the beginning Spell with olo in the middle Use double p but only one r and end in ent Do not put an e after the u as you would in argue Capitalise the word Article when referring to the element of Joomla content One word with capitalisation as shown Ensure it is always capitalised and hyphenated when referring to the Administrator area of Joomla Use backup when used as an adjective as in he had a backup disk in his bag and use back up when using it as a verb as in don t forget to back up your hard drive Cap
38. ys but not for the names of the seasons Use capital letters for religions and religious groups Use capital letters for organisation names commercial governmental and non profit as well as their products and services Use capital letters for references to most numbered or lettered items for example figures tables chapters parts Use capital letters for objects that have individualised names Use capital letters for most acronyms When in doubt check the dictionary Use capital letters for the spelled out version of acronyms only if the spelled out versions are proper nouns in their own right Do not capitalise in the following situations When you want to emphasise something NEVER use all caps to highlight a word only use the formats defined in the Visual Style Guide e The only exceptions to this are within code extracts where it is a direct representation of the code or when representing a screen or system message configured in this way Variable names The initial letter of the first word following a colon if the word is part of an incomplete sentence Numbers versus Words In this type of documentation we will often use numerals in text even those below 10 breaking one of the established writing rules Do not use words when the number is a direct representation of a specific value For example in referring to Joomla Version 1 5 the numeral is in order as it is a direct reference to a numerical sequence
Download Pdf Manuals
Related Search