Rules for Determining Terminology 0. For all rules, priority is general usage, then previous versions of the product, and finally related technology.
1. If a word exists with the required definition, use that word. 2. Do not change the existing definition of a term. If functionality is significantly altered, a new term is needed. 3. Use real words whenever possible. 4. Single-word names are better than multiple-word names. 5. Use terms that fit the current technology and its planned future. 6. Try not to introduce new terms. More terms creates a larger glossary that must be understood, increasing the learning curve, and reducing the audience willing to invest in the product. == Examples == (The numbering does not imply any connection to the Rules.) 1. Do not use "AngleText" for text separated into functional units using angle brackets. General Usage uses "XML". 2. General Usage defines "Document" as "a single unit of textual information". A Related Technology (XML) defines "Document" as "a single unit of textual information conforming to the XML specification". A Previous Version (Lenya 1.2) defines "Document" as "a single unit of textual information conforming to the XML specification with specified security and workflow". No other definition is allowed. 3. General Usage defines "Sitemap" as a single-page directory of a website. A Related Technology (Cocoon) redefines it as XML processing instructions for handling a request. General Usage wins, so find another name for XMAP files. Other technologies use "program", "subroutine", or "servlet" for "processing instructions for handling a request", but none of those fit this technology. I use "XMAP" for this because everyone familiar with the technology immediately understands. A better term would be "route" or "router", but a new term must originate with Cocoon; outside parties could not spread a new term . 4. Lenya 1.2 defined "Asset" as an uploaded file, not editable and barely usable by Lenya. Do not change "Asset" to mean "Part of a Document", or "Any Resource including XML". We can fix the "barely usable" part, but not in a way that significantly changes the definition. 5. Lenya 1.2 defined "Usecase" as "special process separate from the primary process". General Usage defines "Usecase" as "Real world actions required to complete a task". There was a major discrepancy. Lenya 1.4 changed the term to "Module". General Usage defines "Module" as "A standardized component of a system designed for ease-of-use and flexibility". Lenya 1.4's usage conforms to that definition. (And I hope we remove the differentiation between Modules and the primary processing path.) 6. No software uses the term "Nugget". The phrase "I created a Nugget" currently has no meaning. "I created a Document" can be understood by people who are barely computer literate. "I created an Asset" (meaning uploaded a file) is understood by users of Lenya 1.2. "I created a Resource" would be understood by most people. Lenya 1.2 used "Resources" for a variety of additions: static graphics, storage of "Assets", presentation configuration (CSS and i18n), and software plug-ins (such as editors). That was confusing to developers, and created a messy datastore. Lenya 1.4 has not defined "Resource" yet, but should relate to one or more of Lenya 1.2's definitions. Software plug-ins are being defined as "Modules". All graphics should be "Assets" (Why allow static graphics? Let everything be editable, and improve security so the security granted by requiring file system access is unnecessary.) Presentation configuration will be moved inside Modules. While none of the old definitions of "Resource" are needed, the word is already used by Lenya, and should be used before adding a new word. 7. Lenya 1.2 defines "Publication" as "Content and related processing instructions" where "Content" is defined as "(XML) Documents and related Assets" where "Assets" is defined as "uploaded files". People keep suggesting using "Site", "Website", "Book", and other terms for this concept. General Usage defines "Publication" as "A specific issue of a public work including textual information". The output of a Lenya 1.2 Publication is close enough to the General Usage definition that very few people have been confused by the term. If it works, do not break it. 8. "Resource" is better than "ContentItem" because it contains fewer words. === On 2/7/06, Thorsten Scherler <[EMAIL PROTECTED]> wrote: > What both models of http://wiki.apache.org/lenya/GlossaryStructure have > in common is that "content" is stored in a Publication. Now Andreas is > using frequently the word "structure" in referring to the sitetree or > like solprovider is calling it index of a publication. Seeing it from a > different angle a sitetree or index or structure is nothing else then > the typical table of content (toc) of a (text) book. 1. "TableOfContent" is three words where we have been using one ("Sitetree"). It also implies a single structure. 2. "TOC" is not immediately recognizable by people outside the printed paper industry. 3. Andreas uses "Structure" to mean the one and only hierarchical structure of information within a Publication. I think more flexibility would be easy. 4. I use "Index" to refer to an easily configurable internal data structure used to allow multiple "structures", both flat and hierarchical. Notice "internal". The only people aware of Indexes would be: - Programmers of core that implement the feature. - Developers of Modules that concern multiple Resources. ("Resource" being defined as Nodes within Content.) To clarify, the bulk of understanding "Index" falls to the programmers of core implementing the feature. The "live" Module is only concerned with one Resource, so the developer does not need to understand "Index". The "live" Module aggregates the result of the "menu" Module. The "menu" Module creates a list of multiple Resources, so configures a hierarchical Index. The developer of the "menu" Module only needs to understand that properly using XML to configure an "Index" allows using the following line to generate XML about multiple documents: <map:generate type="sitetree" index="myNewIndex"/> The SitetreeGenerator does the work; the developer looks at the resulting XML to see if the Index configuration is correct, then continues writing the Module (probably adding XSL transformations.) Indexes would also be used internally to translate between the ID (or URL) (/section/category/documentid) and the UNID (unique identifier of the Resource in the flat storage of Content) used to retrieve a Resource. Again, use of the Index is transparent to everybody except the core programmers implementing the feature. solprovider --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
