All,
as we have now reached a whopping 115 modules published in the Central
Repository, it starts becoming difficult for end users to find what they
want in the Module Management window. In future, we will add categorization
and better search capabilities but for now we need to rely on good names and
descriptions.
A few months ago, Peter and Gil proposed a set of naming rule but we never
rolled them out. I now re-propose a new set of rules based on their original
work.
If we all agree on these rules, I will add them to the wiki as an official
reference and we will start enforcing them.
The most controversial rule is enforcing the usage of English for module
names (but not for module descriptions - note: the Search function searches
both names and descriptions). The rationale for this rule is to enforce some
consistency and to allow users not knowing the language to know what the
feature is about, even if it is not in their language (think of the case of
a module developed by a Chinese developer in Chinese but applicable globally
- a Spanish user might want to find it and provide a Spanish translation for
this module).
However, I know that not everybody agrees with this rule and possible
alternatives are:
1. All module names are in English except for the modules that are a
translation of another module. For example, the translation of the Tax
Report Launcher will be called "Generador de declaraciones de impuestos" (I
believe that this is Ismael's recommendation) while the rules below
recommend "Tax Report Launcher Translation: Spanish Spain (es_ES)"
2. The name of a module is in the base language of the module (the name
of a module in Chinese would be in Chinese).
Please let me know if you have any opinions on this topic and what you think
of these rules
Thanks,
Paolo
----------------
Naming guidelines for modules.
It is important to select an appropriate name for your module in order to
make it easier for users to recognize it both in the Forge and in the Module
Management window.
Here is a set of naming guidelines that we ask module author to honor:
Branding rules:
- The module name should match the project name in the Forge (optional)
- Module names should not be longer than 5 or 6 words and less than 60
character long (optional)
- Module names cannot contain the word "Openbravo"
- JSON REST Web Services: CORRECT
- Openbravo JSON REST Web Services: INCORRECT
- Exception to the previous rule: modules that Openbravo S.L. decides to
market as products rather than modules:
- Openbravo QuickStart Template: CORRECT
- You do not need to specify the Openbravo version in the module name:
- Translation: Arabic Saudi Arabia (ar_SA): CORRECT
- Translation: Arabic Saudi Arabia (ar_SA) for Openbravo 2.50:
INCORRECT
- Module names should not contain the word "Module"
- Copy Role: CORRECT
- Copy Role Module: INCORRECT
Language and grammar conventions:
- All module names must be in English. The module description and help
can be in any other language.
- Non English proper nouns are accepted as part of a module name
specified in English
- Tax Report: Modelo 349 (Spain): CORRECT
- Tax Report: Form 349 (Spain): INCORRECT (rationale: Modelo 349 is a
proper noun and should not be translated)
- Informe Fiscal: Modelo 349 (Spain): INCORRECT
- The module help must be different than the module description
- Grammatically, module names should be consider proper nouns and you
should capitalize the first letter of every word in the module name (with
the exception of short words and acronyms)
- Initial Data Load: CORRECT
- Initial data load: INCORRECT
- Direct Debit Form of Payment: CORRECT
- Direct Debit Form Of Payment: INCORRECT
- Three Digits ISO Country Codes: CORRECT
- Three Digits Iso Country Codes: INCORRECT
- You should avoid using numeric characters to express quantities (they
are OK in codes and dates)
- Three Digits ISO Country Codes: CORRECT
- 3 Digits ISO Country Codes: INCORRECT
- Chart of Accounts - PGC 2007 General: Spain: CORRECT
- Tax Report: Modelo 349 - Spain
- Module names should not end with a full stop:
- Initial Data Load: CORRECT
- Initial Data Load.: INCORRECT
- Module description should end with a full stop
- Generador de declaraciones de impuestos. Traducción al español
(español España) del módulo Tax Report Launcher.: CORRECT
- Generador de declaraciones de impuestos. Traducción al español
(español España) del módulo Tax Report Launcher: INCORRECT
Specific types of modules:
- Core translations (translation of Openbravo Core) should follow the
convention:
- "Translation: $LANG $COUNTRY ($CODE)"
- Example: Translation: Arabic Saudi Arabia (ar_SA)
- Module translations (translations of modules other than Openbravo Core)
should follow the convention:
- "$MODULE NAME Translation: $LANG $COUNTRY ($CODE)"
- Example: Tax Report Launcher Translation: Spanish Spain (es_ES)
- The description for module translations should include an appropriate
translation of the module name in the target language as well as both the
name of the language and the name of the country in the target language:
- Example:
- Name: Tax Report Launcher Translation: Spanish Spain (es_ES)
- Description: Generador de declaraciones de impuestos. Traducción
al español (español España) del módulo Tax Report Launcher.
- Chart of accounts modules should follow the convention:
- "Chart of Accounts: $COUNTRY"
- Example: Chart of Accounts: France
- For countries with multiple charts of accounts, use the conventions
- "Chart of Accounts: $TYPE - $COUNTRY"
- Example: Chart of Accounts: PGC 2007 General - Spain
- Example: Chart of Accounts: PGC 2007 PYMEs - Spain
- Tax configuration modules should follow the convention:
- "Tax Configuration: $COUNTRY"
- Example: Tax Configuration: France
- Tax report modules should follow the convention:
- "Tax Report: $FORM_NAME - $COUNTRY"
- Example: Tax Report: Modelo 347 - Spain
- Region modules should follow the convention:
- "Regions: $COUNTRY"
- Examples: "Regions: Brazil"
- NOTE: whenever the regions of a country are called something other
than regions, you can use the correct term in the module description.
Example:
- Name: Regions: United States of America
- Description: US states.
- Report modules (other than tax reports) should follow the
convention:
- "Report: $REPORT_NAME"
- Example: Report: Shipments Awaiting Invoice
- Skin modules should follow the convention:
- "Skin: $SKIN_NAME"
- Example: Skin: Blue Sea
- Tutorial modules (provided as examples to illustrate how to develop
modules) should follow the convention:
- "Tutorial: $TUTORIAL NAME"
- Example: Tutorial: Solitaire
- NOTE: in future, we might use these naming convention to automatically
categorize modules based on tags.
------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com
_______________________________________________
Openbravo-development mailing list
Openbravo-development@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/openbravo-development
