Documentation Conventions and Nomenclature

From MozillaWiki
Jump to: navigation, search
Go to the Open Source Eudora Project IndexGo to the Open Source Eudora Documentation IndexDownload Eudora OSEOse-navstack.png

There are a number of subtle complexities involved in the documentation process. A lot goes into making sure things are clear and concise, and presented in a way that keeps readers moving smoothly along instead of stopping them in confusion.

Sometimes, that needs a bit of explaining just so everyone’s on the same page...


Where’s the Beef?

When someone buys a computer program for a particular operating system, they usually expect the documentation to cater specifically to their needs on that particular platform. Because Eudora OSE is even more of a multi-platform project than in the past, embracing the Windows, Mac, and Linux worlds from a single unified codebase, it is even more important to be able to address the needs of all users from a single set of documentation. As a general rule, this is not particularly difficult, however there are sometimes program elements that, while common across all platforms, may appear in different places and under different names.

The most conspicuous of these migratory elements is the preferences window. Each operating system has its own standard convention for the name and location for this universal component:

  • Windows: Tools > Options
  • Mac: Eudora > Preferences
  • Linux: Edit > Preferences

It is important in the documentation process to be able to refer to the same thing once, in a way that clearly communicates the intent to users of all platforms.

Instead of using a platform specific format like Tools > Options > [something] to indicate where you should go to find that thing in Windows, and duplicating that as Eudora > Preferences so as not to confuse Mac users, it is expected that users of a particular platform will have a knowledge of the standard location for program options.

In the Eudora documentation, the standardized, universal way of referring to the program options interface, no matter where it happens to appear on your system is [Options/Prefs window] > [something]. And as a further educational bonus, every time it appears, it will link back to this explanatory page.


What’s in a Name?

Because the underlying code is completely new, and all of the features have to be reimplemented, there needs to be a way of referring to the different epochs of Eudora’s development without becoming tedious or overly redundant.

Conversationally, the following abbreviations have gained some traction, and may sometimes find their way into the documentation:

  • classic Eudora (abbreviated cE) is taken to mean Eudora 7.1 or lower, and by extension the original proprietary Qualcomm codebase.
  • ≤E7.1 also refers to classic Eudora.
  • OSE refers to the first Open Source version of Eudora, built on the Thunderbird codebase.