Features Roadmap Download Support

Technical writing for HERMES

In software, the phrase "technical writing" refers essentially to all writing in a natural language; editing and translating documentation all falls under this banner. Maintaining this Web site---a role called front-end development---also fits more neatly into this category than into "development" in general, because Web sites are written in much the same way as Windows help files. The primary tool of the technical writer, be he a translator, editor, or content creator, is the text editor; as this is a collaborative project, a revision manager is also needed.

For someone familiar with the UNIX style of operating system (Linux, AIX, BSD, or OS X), it is strongly suggested to have the latest version of GNU Emacs, Spacemacs, and either Mercurial or Sourcetree installed; for a Windows user, these recommendations still hold true, but a generic text editor is also an option (generic text editors won't highlight HTML tags, though, so be careful).

Process

The procedure for contributing art, technical writing, or translations to the HERMES project is broadly similar across all our products, irrespective of the nature of your contributions. We use a revision control system called Mercurial to track changes and even revert them if necessary; moreover, the "authoritative" version of all work is kept on a server called Bitbucket.

  1. Contact the team lead, Nicholas Edward Werner-Matavka, by electronic mail to be given "commit privileges" on Bitbucket. Mention your planned type of work (for example, "I speak English and Swahili; I wish to translate between the two").
  2. Download Sourcetree and make sure you have a good text editor installed on your computer. We recommend Spacemacs but any generic text editor will do.
  3. During the Sourcetree installation process, you will be prompted to choose between Cloud and Server. Click on Server, then input https://bitbucket.org/team-hermes/hermes-mail-documentation/src/default/ as your "base URL".
  4. In Sourcetree, click New, then click Clone from URL. Enter https://bitbucket.org/team-hermes/hermes-mail-documentation in the "Server" field. After a few minutes, you will have an unabridged copy of HERMES' documentation, art, Web site, and essentially everything that isn't actual source code.
  5. Work.
  6. When you're finished doing a discrete set of tasks (like, for example, translating the Help file to Swahili), "commit" your changes; at the end of every day you work, "push" them so they're reflected on the central server.

NOTE: You can clone (download) the repository to any directory on your computer, which can run whatever operating system you like. For this reason, we have to introduce a naming convention. Subdirectories of your private copy of the repository will be separated by the oblique stroke (/), and the root (uppermost directory) of the repository will be represented by the oblique stroke in isolation. For example, if you're a Windows user who cloned the repo to C:\Users\John\Desktop\MyWork, we will refer to that as simply /, and C:\Users\John\Desktop\Mywork\Documents\Mac will be /Documents/Mac/.

Documentation

At the present time, our priority agenda vis-a-vis documentation for HERMES Mail are as follows:

  1. Ensuring that the Windows Help file reflects the present user experience of HERMES Mail, as opposed to the old Qualcomm Eudora. For example, because HERMES Mail 8 is a free program, references to registration and "Paid Mode" must be systematically removed.
  2. Creating a hard-copy HERMES Mail manual using whatever Eudora documentation can be found as source material (Help file, dummies' guides, etc).

In a way, the tasks feed into each other: the manual and Help file ought to be as mutually similar as possible, with allowances made for the intrinsic difference in media. This is not to say that the Windows Help file is in any way to be considered the "master copy"; you are encouraged to use other sources, such as Eudora books, to fill out topics that need explanation (suitably paraphrased, of course).

The foregoing paragraph might be a little hard to digest. Put simply, the gist of working on documentation is this: you are in charge of making sure that a newcomer to a HERMES product, someone who hasn't ever used it before, can understand it. If a developer adds a feature to it, it's your job to ensure that this feature has a page about it in the Windows Help file, taking the computerist through the dialogue boxes he interacts with, explaining which buttons to click, and so on. If a feature is removed, you don't want to confuse the computerist, so you need to remove it from the Help file, too. We're also making a manual in printed form, but books are not Web pages, so references to clicking on such-and-such a link are nonsense.

As a writer of documentation, you will mostly be working in /NewHelp8/en/_HelpSource/HTML/ and /Documents/Hermes/. The former contains the files that will be used to compile three types of Windows help file (in its latest form, more or less a self-contained Web site that runs on your computer). The latter contains the files that will be used to print the HERMES Mail manual.

The online documentation (the Windows help file) is written predominantly in a human language (in general, English), interspersed with formatting instructions in a computer language called HTML. Many free tutorials on writing good HTML exist online, but for the most part, you can play it by ear. The offline documentation (the book) is written once again in English for the most part, with the formatting being in LaTeX this time around. One of the best LaTeX tutorials around is called "Typesetting with LaTeX: a guide for novices" and is available on Lulu and Amazon.

Translation

The fundamental description of this role is self-explanatory: you will be translating different parts of the output of the HERMES project from English into another human language. There are two halves of this, though: one is translating documentation (what the computerist reads when he needs help), and the other is translating the user interface of the program (what the computerist interacts with in the first instance). The priority, at the present time, is to get the documentation of HERMES Mail for Windows translated.

As a documentation translator, you will mostly be working on the same parts of the codebase as the documentation writers, with one difference: you will be using the English documentation as a source, and you will create a new directory for the language into which you will be translating, called the target.

For example, suppose Lucius Cicero wants to translate into Latin. To begin, he first checks if there's a directory named /NewHelp8/la (two-letter code for Latin); there isn't, which means he's the first person to attempt this. He therefore copies /NewHelp8/en/ into /NewHelp8/la, then navigates to /NewHelp8/la/_HelpSource/HTML and begins work. Naturally, all the files are there in English; all Lucius needs to do is open them up, one by one, and translate sentence by sentence.

The same sort of workflow applies for translating the book form of the documentation. Lucius begins by copying /Documents/Hermes/en/ to /Documents/Hermes/la/; there's only one text document there, and that's all he needs to translate, again, sentence by sentence, in situ.