modulus blog

When I draft my e-books, my editor often complains about my use of the abbreviation “e.g.”. She prefers me to write “for example” and, even then, there is always a struggle for me to get the commas in the right places.

Even worse, “for example” often is not all that I wish to say; often I’m trying to say something of the style “that is, for example”, so I wind up doubting whether I’m really wanting to “i.e.” or “e.g.”

I’ve decided to cut the Gordian knot; from this day hence, when appropriate I will use the newly coined T.L.A.* “i.e.g.”, meaning “that is, for example,”. I’m sure you will find i.e.g. a perfectly cromulent T.L.A.

* T.L.A. = Three Letter Abbreviation.

Google vice-president of search product and user experience, Marissa Mayer made an interesting observation recently, when speaking of on-line newspapers:

I can go to various newspapers and when you scroll down to the bottom, what do you do next? There were related stories and related videos but those were up on the top. So now the most committed user – the one that reads through the entire piece – is now looking at the bottom of the page with nothing to do.

It is well worth while looking at each of your web pages with the specific aim of ensuring that there is something engaging to reward your most committed site visitors, at the end of each article, at the bottom of each page. This is especially true for longer articles or pages.

When specifying text size in HTML markup by way of the font-size attribute in CSS, the units used can be either absolute or relative. Absolute units (such as pixels) mean that the website designer retains more control over the appearance of the page, but that requests from web browsers for larger or smaller sizes will be ignored. When relative sizes are used (such as ems or percentages) some additional testing is needed to ensure that the page does not become illegible or jumbled at large and small point sizes, but the degree of convenience offered to those whose vision is less than 100% is, in my opinion, well worth the extra five minutes of testing. Furthermore, relative sizing allows for both automatic and manual adjustment of the font size on devices such as mobile ‘phones.

I visited 40 randomly-selected websites and checked each for compliance with requests from the web browser to increase or decrease the text size (note that this is not the “zoom” function present in some browsers, it should affect text only. The results are as follows:

“Full” means that all text on the site resizes as requested by the browser, and that the end result is still legible.

“Partial” compliance means that while much of the text might resize as requested, some of it does not (or the site becomes illegible due to text overlaps); the most common symptom here is menu text which stays at the same fixed size.

“None” means that, apart from some minor and accidental spacing changes, none of the text responds to requests for size changes.

Observant readers will know that this is not a recipe blog, except for programming recipes. Nevertheless, this one is about chili sauce.

ingredients

• 550 gm tomatoes
• 400 gm brown onions
• 80 gm jalapeño peppers
• 20 gm red chilis
• 1 lime
• 3 cloves garlic
• 1 cup brown vinegar
• 1 cup water
• 1/3 cup sugar
• 1/2 tsp salt

method

Dice the tomatoes, onions, peppers, chilis and garlic. Add the zest and juice of the lime and other ingredients, bring to the boil in a heavy
saucepan and then slowly simmer for 30 minutes. Blend with a stick blender. Makes about 1.5 litres.

As I often do, when planning development of my text processor I consider first what capability Microsoft Word has. I have Word 2000; its “Thesaurus” function is really a list of synonyms (with the occasional antonym) rather than a proper thesaurus. When you look up “updated”, the Thesaurus form looks like this:

It’s not very pretty. There are four input boxes, four buttons, three labels and a control alignment which appears to be largely random. The substantive content is a flat list of synonyms. It occured to me that there might be better designs available.

After some trial and error, I have ended up with the following design in my text processor, Weblex:


The synoym list uses a Windows Tree-view; when you select a synonym by clicking on it, synonyms for that synonym are presented, as is the case for “modernism” displayed above.

There are two input boxes and three buttons, one label. One of the buttons is additional to the Word fuctionality (”Find on WWW”), so the net reduction in clutter is quite significant.

The moral of this story is that, despite the owerwhelming number of designers, software engineers, ergonomists, hair-dressers and spin doctors in the larger software development firms, it is still not only possible but indeed feasible realistic practical workable viable to compete with them on good design.

In 1980, Martin Porter published a stemming algorithm for English words; stemming is essentially the reduction of a word to its stem by removing its suffixes. Thus, for example, the word “stemming” can be reduced to its stem “stem” by use of Porter’s algorithm. This is immediately useful, since, when searching for the word “stemming”, we can also search for the word “stem”. Normally “stemming” will not match with “stem”, but, when reduced to its stem by suffix removal, it will.

The Porter algorithm removes about 150 common suffixes by way of an algorithm that occupies about 400 lines of Pascal or about 100 lines of Perl, courtesy of the latter’s regular expression library. For those looking for implementations of the algorithm in a variety of languages, the best starting point is Martin Porter’s own website,
tartarus.org/~martin/PorterStemmer/.

The algorithm is useful for searching (Google makes use of it) and a variety of language processing tasks. One interesting use is to find alternate bases for synonym searching. In my “weblex” text editor, when a user seeks synonyms for the word “interesting” the following happens:

1. synonyms for “interesting” are sought in the synonym dictionary and presented to the user
2. the stem “interest” is determined using the Porter algorithm
3. synonyms for the stem are sought
4. about 150 suffixes are added to the stem and, for each Frankenstinean suffixed form, synonyms are sought and presented to the user together with the suffixed form

One possible optimisation would be to check whether each suffixed form is an English word before seeking synonyms, but as the process descibed above completes in milliseconds this
does not seem to be necessary.

Software documentation and comments are highly variable in quality and usefulness. At the useless end of the spectrum are the detailed source comments which tell you what the next line of code is going to do. As the next line of code tells us exactly the same thing, this is at best pointless; at worst, when the comment does not accurately describe what the next line of code is going to do, it can be seriously misleading; here’s an example of what I’m describing:

#increase each object's value by 10
for (sort keys %objects){
$_ += 10;
}

Perl programmers will notice that the code does not increase the object values, but rather the keys of the %objects hash, so the comment is not only redundant but also plain wrong.

On the other hand, very high-level, abstract documentation which tells us what a program or function library does conceptually is only useful in a very high-level, abstract sort of way.

One type of documentation which is much more successful is the “Javadocs” style of functional documentation, which describes each function (or subroutine or procedure) principally in terms of its inputs and outputs. “Javadocs” is a documentation methodology maintained by Sun Microsystems, originally intended for documenting Java functions, but easily adapted to almost any other language. Here’s an example of the use of Javadocs on a PHP function:

/** * Returns the capability for a given capability name.
 *
 * @author Modulus Pty. Ltd. - prh
 * @version 2008 1.0
 * @param $id unique string id of the device
 * @param $name string name of the capability
 * @param $fallback boolean for considering fallback

 * @param $fallbackChain array of strings, where known, provide this to avoid unnecessary repetitive lookups
 * @return string capability

 */

function lib_getCapability($id, $name, $fallback, $fallbackChain) {
   ...
}



This documentation is immediately useful in the source code for developers maintaining or altering the source code. Furthermore, the effort required to create and maintain the documentation is quite limited in relation to the benefit derived. However, you may wish to publish an API to your functional library without publishing the source code. One way to do this is to use our javadoc.module,
which, for a modest $19.95, creates elegant, valid and conformant XHTML documentation from Perl, PHP, Javascript or Java source code. Here’s an example of the output generated:

RACI aide memoire

Before discussing RACI variants, let’s recall the basic RACI model; RACI is a technique used within BPM to clarify responsibilities
and accountabilities for processes. The term RACI is an acronym for “Responsible”, “Accountable”, “Consulted” and “Informed”, and the
technique of RACI is to determine, for each and every process, who is Responsible for the execution of the process, who is Accountable for the outcomes of the
process, who is Consulted in the execution of the process and who is Informed by the process. These four characteristics of people involved with managing business
processes describe each of the key player’s degree of involvement in and liability for the process.

There are a number of models which vary or extend the RACI model. These variants exist partly due to a slight initial awkwardness in distinguishing between the “Accountable” and “Responsible” roles
in the traditional RACI model.

Our purpose in discussing the variants here is to enable you to identify and understand them; we do not suggest that you adopt any of these variants as the benefits of the variants do not, in our view, outweigh the downside
of using a non-standard model. We believe that standard RACI has the necessary and sufficient role identifications to support process-based management.

RACI-VS

RACI-VS adds two roles, viz:

• “Verifies” – the party that checks that a product or service matches its established standards and
• “Signs-off” – the party who approves the verification step and authorises the release of the product or service

This variant adds minor roles and potentially introduces confusion between the two roles it introduces. Additionally, it is quite common for verification processes to be separate processes from the main processes which generate
the product or service to be verified and thus these roles may only exist in the verification process, again inviting some confusion between the verification role and the verification process.

CAIRO

CAIRO adds the “Omitted” role (or, as our American friends might prefer, “Out of the Loop”). This extension is potentially useful in identifying specific cases where an organisational role, which might be thought to be involved in a
process, is specifically not Accountable, Responsible, Consulted or Informed. On the negative side, it should be noted that most organisational roles are not involved in most processes, so this extension runs the risk
that numerous positions need to be identified as “Omitted” for each process.

RASCI

The RASCI extension adds the “Support” role to the basic model, allowing for people who are co-opted to support the “Responsible” role in performing the task. There is a subtle distinction
between the “Consulted” and “Support” roles, as the latter may be tasked with performing part of the work of the “Responsible” party.
Again, the value of the extension seems limited relative to the cost of non-standard terminology.

RACI (Alternate mapping)

The one variant of RACI which addresses the most common RACI difficulty is the alternate mapping where:

• “Responsible” is the person responsible for the performance of the task; this is roughly equivalent to the standard meaning for “Accountable” and
• “Assists” is the party who assists the “Responsible” party in performance of the work and may perform the bulk of the work

This variant appears, at first sight, to resolve the difficulty in standard RACI of understanding the relative accountabilities and responsibilities of the “Accountable” and “Responsible” roles but, in our view, only weakens the
proper understanding of the roles. The notion of someone whose role is purely to “Assist” weakens accountability and, consequentially, makes process-based management more difficult to drive through.

This article is an extract from the “Teal Book” (Identifying, Documenting & Analysing Business Processes) available for on-line purchase at e-books.

We become accustomed to seeing system messages such as “3 file(s) deleted.” However, this smacks of laziness. One useful function that can be written in your programming language of predilection is plural(). The plural() function is fed parameters of the number and word to be inflected and returns the word approriately inflected. For example, if we call plural(3,'file') it should return ‘files’. When we call plural(1,'file') it should return ‘file’ in order that we can say “1 file deleted” and, oddly enough, plural(0,'file') should return ‘files’, in order that we can say “0 files deleted.”

Of course, English formation of plurals is not regular, so a good implementation of the plural() function would have to deal with the many exceptions in pluralisation, such as class=>classes, potato=>potatoes, data=>data, calf=calves etc. Even then, when the system message is “3 files were deleted”, we also have to deal with the declension of the verb “to be” so as not to end up spouting nonsense like “1 file(s) were deleted”; to avoid the endless complexities of declining irregular verbs, it seems best to avoid verbs in locations in system messages where number is important, i.e. “3 files deleted” rather than “3 files were deleted”.

So, how do we deal with the apparently overwhelming complexities of English grammar, to put out a simple but gramatically-correct system message when we delete a number of files? The resolution is surprisingly easy, achieved by modifying the form of the function plural() so that it takes three arguments: the number, the singular form of the word and the plural form of the word. Thus plural(3,'platypus','platypuses') will return ‘platypuses’, whereas plural(3,'radius','radii') will return ‘radii’, without the need for a long and complex function. Thus "1 "+plural(1,'file,'files')+plural(1,'was,'were')+" deleted" correctly issues
“1 file was deleted” whereas "3 "+plural(3,'file,'files')+plural(3,'was,'were')+" deleted" correctly issues “3 files were deleted”.

Here is the whole of my Perl plural() function:

#**
#* Returns a string with correct plural treatment.
#*
#* @author Modulus Pty. Ltd. - prh
#* @version 2008 1.0
#* @param $nr the number governing the result
#* @param $sstr the singular string e.g. 'match'
#* @param $pstr the plural string e.g. 'matches'
#* @return $sstr or $pstr
sub lib_plural{
   shift == 1 ? shift: $_[1];
}

This morning I took on the task of merging 200 articles which have been published over four years at Kevin Dwyer’s Change Factory website. The aim of the exercise is to create a compendium of change management and business process management advice from the articles; they will be sorted into appropriate chapters, Kevin will write some brief “glue” text and an introduction, but we want to do it without wasted effort.

Fortunately the articles are quite consistent in format, as they are written using a template. I wrote a Perl program to work through the articles directory, retrieve each article, remove its headers and footers, discard some unnecessary content, and add the article to the (large) merged HTML file. After testing its basic functionality and fine tuning for a couple of minor exceptions, the HTML file was created, weighing in at 1.1 MB, and then read in to Microsoft Word and saved as a Word document, ready for Kevin to add the glue text and introduction. The Perl program is, in itself, quite unremarkable; any programmer could write the same in a language of their choice in half an hour.

It is convenient to have each article start a new page, but as HTML does not have a paging paradigm, where to start? This turns out to be dead easy; the aforementioned Perl program creates a level 2 HTML header block for each article, e.g. <h2>This is an Article Title</h2> with the article’s title. When read into Microsoft Word, these were automatically transformed into Words “Heading 2″ elements. All that remained was the page break, and this was readily achieved by creating a style for the merged HTML document using the print-oriented part of the CSS 2 specification, viz:

h2 {
   page-break-before: always;
}

Word (which does have a paging paradigm) recognised the instruction and promptly inserted page breaks before each “Heading 2″ element, just what was wanted. It sometimes surprises me when things turn out to be so simple to achieve. Something a bit more sophisticated could be achieved using the CSS 2 “widows and orphans” controls, but as this Word document is a means to an end rather than a finished product, I heeded Voltaire’s advice that “The perfect is the enemy of the good.”