I'm back on the market for workÉibhear, 2016-09-01 18:19:00 IST Following an excellent year-and-a-half as a consultant solutions architect in AIG Europe in Dublin, I'm back on the hunt for a new job. If you're looking for a solutions architect with a keen focus on delivery quality, perhaps you might want to check out my Hire Me! page, or go directly to my CV. I will be available to start in a new position on the 26th September. My contact details are in both locations. Meeting Terence Flanagan, a general election candidate [Updated slightly]Éibhear, 2016-02-26 22:09:00 GMT This morning I met Terence Flanagan, and it didn't go well for either of us. Mr. Flanagan is a Renua Ireland candidate in Dublin Bay North in the 2016 general election (taking place today, 26th February, 2016). He was elected in the last general election in 2011 as a Fine Gael candidate in the former constituency of Dublin North East1. Some time after his old constituency was abolished and before he left Fine Gael, I met him outside the door of the local supermarket. He was clearly on a getting-to-know-his-new-constituents gig. I spoke to him briefly; raising some matter of concern, the nature of which escapes me. I gave him my contact details (I think by giving him my personal card) so that he could contact me. I have no memory of him ringing me, and a search of my e-mails suggest he didn't get back to me. Except, he did. Yesterday. The day before the election. With this: Update: In case you can't see the image, it's a screen-shot of an SMS I received, which reads "FROM TERENCE FLANAGAN: Thank you for the courtesy shown to myself and my team during the General Election Campaign. I would be grateful for your support tomorrow. Many thanks, Terence Flanagan. OPTOUT 50123" and the timestamp on it is 21:18, Feb 25. This text came in while I was waiting for another one, and it was irritating and frustrating to be presented with it. This morning, as I was walking past a busy junction, I saw Mr. Flanagan canvassing – obviously hard – for the last few votes from the last few undecideds. I decided that I was going to raise my concern at being contacted like this out of the blue. I went up to him, and as I approached him, I was not happy with how I was feeling. He saw me approach, seemed to like the idea and put out his hand to greet me with "Hi. Terence Flanagan". It went quickly downhill from there: "I know who you are," I said, keeping my hand down. "I spoke to you some years ago, and gave you my number. I never heard from you. Until I got that text message from you last night. I didn't give you my number to spam me. There's no way you're getting my vote!" I genuinely could not believe the rage I got into. I went from annoyed when I decided to talk to him to furious as I walked away from him (with him calling after me "You can unsubscribe, you know!"). Mr. Flanagan, if you're reading this2, a fundamental principle of data protection is that a public figure like you is not allowed to use my contact details to contact me in this manner except with my express consent. It's possible that politicians have carved out an exception for themselves from these legal requirements. I remember that there was an attempt to do just that a decade or so ago. It doesn't change the principle: I did not consent to receiving that SMS from you. I can only hope that sending "optout" to 50123 will really remove my number from that spam list. Will it get Mr. Flanagan to understand that I don't want to be contacted in this way, I wonder? Footnotes: 1 He was first elected in 2007. 2 Which I doubt! The case for a retract buttonÉibhear, 2016-02-04 13:27:00 GMT We're gearing up for an election here in Ireland, and many are well prepared. For example, just a few days ago, Politwoops Ireland was launched. Others are not so prepared: many candidates in this election will go back through their twitter time lines and remove those tweets that will inhibit or – at least – not help their re-election campaigns. I've often wondered why people delete tweets. There are many reasons, and – in my opinion – not all of them are addressed by deleting the tweet, but that's all there is. Perhaps there's a misspelled word that ruins the tweet (as twitter doesn't have an "Edit tweet" option) and you want to do it again1; maybe it's because you replied to the wrong tweet or mentioned the wrong user; maybe it is truly embarrassing and will affect your career or personal relationships; or maybe it's because you're a public figure and you want to reduce the risk of being called out on a contradiction you know you're making. As I said, there are many possible reasons, and the above is only a set of examples. For public figures, the likes of Politwoops Ireland don't care for the reasons1; it'll just retweet the deleted tweet all the same. On the 2nd February this year, The Intercept published a note to its readers calling out how a staff reporter had engaged in unethical journalism: faking quotes, faking people for fake quotes, etc. The editors have conducted a review of this journalists posts, and have updated them to highlight the items of concern, going so far as to retract one story in full. What's noteworthy, though, is that The Intercept didn't remove or delete the story. I believe this is appropriate for a number of reasons. Deleting the story pretends it doesn't exist, but those affected by it will remember it. The best place to note that the story has been retracted is at the same address that the story was published. In the internet world, this is much easier than in the paper world, and anyone looking for (and finding!) the original story will be informed immediately that it has been retracted, and why. Twitter should have a "Retract tweet" option, just like and beside the "Delete tweet" option. Instead, however, of removing the tweet, it will be marked as having been retracted. The advantages I see with this include: Everyone who finds the tweet will see straight away that you don't stand over it any more. Readers can be directed to the tweet's conversation where you can take the opportunity to explain why you've retracted it. Those who have replied to it, or to another tweet in the conversation, and those who have retweeted it (and those in conversations from the retweet) can all be informed that the tweet has been retracted, which will prompt them to review it and the reasons offered for the retraction, and to assess the conversations and their contributions to them. Perhaps – and of course I can't make any promises here because I've nothing to do with it – all the Politwoops accounts would respect retractions and not bring them to the attention of their followers. The model here is how the likes of the @congressedits and @oireachtasedit twitter accounts work: when a user from within the networks of these organisations make a change to a Wikipedia page, it will be tweeted if the change is made anonymously, but not otherwise. Similarly, Politwoops should not retweet retracted tweets, which would respect the open approach the politician is taking. It would be interesting to see what people think. Footnotes: 1 This is the only reason I've had to delete tweets. Stealing from the public domain is still stealing [Updated]Éibhear, 2016-01-16 23:20:00 GMT In response to this story in the Irish Times (regarding the Fianna Fáil bill to return Ireland's National Anthem into copyright, also reported in the Journal.ie), I sent a letter "to the editor". Below is a marked-up version of the letter, showing the differences between what I sent and what was printed. Striken-through text was removed by the editor and UPPER-CASE TEXT WAS ADDED[See update 1 below]. A chara, Copyright infringement happens when someone copies a work without the permission of the copyright holder. The correct use of Copyright theft is when there is a claim to a copyright where there is no entitlement to it. Plagiarism is an example of copyright theft. So, too, is putting under copyright a work that is already in the public domain. Senator Mark Daly's attempt to steal REMOVE Amhrán na bhFiann from the public domain because he doesn't DOES NOT like how it was IS used BY SOME is an extremely A dangerous move ("STATE SHOULD HOLD COPYRIGHT TO NATIONAL ANTHEM, DALY SAYS", JANUARY 15TH). Kudos to his colleagues and the Department of Defence for not supporting it. The use of copyright in this way is itself inappropriate, and would present a precedent to those other copyright maximalists who seek to appropriate the public domain to themselves. For as long and Ireland remains respectable, she and her national anthem will be respected by those for whom this is important. The public domain is already under a huge amount of pressure, so it's IT IS refreshing to see that it, too, has the respect of many in the Oireachtas. I suggest Senator Daly uses a mechanism other than copyright theft to censor expression he doesn't approve of. Is mise, … I'm sure the pragmatic reason of "space" is why the core emphasis of my correspondence was removed. There's a lot more to be said about this. The long and the short of what Fianna Fáil and Senator Daly are trying to achieve can be described in one word: Censorship Copyright has no business being used to stop someone from using a work in a way you don't approve of. That's not what it's for. Update 1 An earlier version of this post attempted to represent text added by the Irish Times in underline, using the current convention. That didn't work, so this update changed that to bold. Update 2 My updated version didn't work, either, so I have updated it again. Beach ArtÉibhear, 2015-08-20 23:08:00 IST I was at the beach today, and drew this in the sand: It took about 30-40 minutes to complete. It was cute watching how people would walk towards it and then veer around it. Parking in ClontarfÉibhear, 2015-08-02 23:24:00 IST If you've ever attempted to drive up or down the southern end of Vernon Avenue, you have probably been blocked by traffic caused by cars parked illegally. Here is how it works. Documentation and versioning, Part 3 of 2Éibhear, 2015-07-31 12:34:00 IST In part 1 of this series of 2 – now 3 – posts, I highlighted some of the worst examples of when document versioning can go wrong. In part 2, I lay out some guidelines that will help keep document versioning under control such that it's understandable and predictable. In this part, part 3 of 2, I close off that list and make a recommendation at the end that would greatly help putting my guidelines into practice. As outlined in part 2, the following is a summary of my recommendations. Use only one versioning system for all your project's artefacts. Use a document properties to record version information Maintain documents in a networked location, and use URLs. No embedded documents Remove older versions out of the way. No version information in file-names. Use a project librarian Make documents easy to get by making them easy to produce properly. I outlined my reasons for the first five in the last post, and here are the last three. Don't put version information into file-names. If you agree that documents should be passed around as an address or link – rather than as an attachment – and that older versions should not be in the same directory as the current version, then this recommendation becomes logical: Don't permit the names of the files that contain document to express any kind of version information. If, say, you pass around a link to the document BusinessRequirements_v0.2.odt, then as soon as v0.3 is announced, that link will either be pointing to the wrong document, or to an address that no longer exists. The latter can be annoying for the person trying to review the document, but the former could cause more serious problems, as the wrong version will be accessed. Similarly, if you operate the rule of keeping only one version of a document in the directory it is to be found, then putting version information in the file name doesn't make a great deal of sense, and may cause confusion. If, however, you mandate that document file names1 should not make reference to the document's version, then you derive the following 3 benefits: All e-mails and other resources that provide the document's address will link to the correct version of the document at all times. Visitors to the document's official directory will be without doubt that the only document with BusinessRequirements in its file name is the current version of the business requirements document, especially as it's called BusinessRequirements.odt. The maintainer of the document has now one location fewer in which to update the document's version number, reducing yet more the risk of internal inconsistency. Use a project librarian A project should appoint one member to be a librarian. This person would set up the document repository and be a document reviewer, looking for compliance to the project-specific rules on document versioning. If this person has early visibility of the documents-in-draft, then compliance advice can be given early, which will help keeping things in line. This wouldn't be a full-time role, of course, but it should be filled by someone on the project. That way, you have someone who's close to the work, and its goals, rather than someone who's sole job is to declare rules for others to follow. Make documents easy to get by making them easy to produce properly. One of the hardest things to do for someone working in the earliest stages of a project is to start preparing a mandatory document. "Is there a template?", "Can I use a previous version?", "Where will I put it?", "Who will review and approve?", "What's the correct way of passing this around?", "How long will this take to prepare, and how much of that time will be spent on document compliance?" A project office worth its name should have all these answers available for you in an easy-to-read and easy-to-follow format. The goal around a document maintenance frameworks should be two-fold: It should be easy to do things right; and it should be hard to do things wrong. Using a revision control system As I said in part 1, traditionally I have required the same revisioning regime for our documents as for our code files. Consequently, I have always maintained technical documents in the project's revision control system, and I have required my teams to do the same. The primary reason for this is straight-forward: as we create project labels or tags declaring that our development has reached specific milestones, it's a good idea to make available to a reviewer the documentation that is associated with that specific version of the deliverable. For example, if the label implements the requirements as they were agreed in March, the delivery should be assessed against that version of the requirements document, and not the version that was agreed at the end of May and not yet sent to the development team. If the correct version of the requirements document forms part of the label, then there is less difficulty in validating the delivery. As well as the above, excellent, reason, consider how maintaining your project documents alongside your technical files – in a dedicated revision control system like, for example, subversion, git, TFS (if you insist!) – can help with my guidelines. By using a revision control system, you can rely on its scheme for incrementing revisions. You don't have to devise one yourself. Also, you could go further and using tagging or labeling to mark files as DRAFT, FOR APPROVAL and COMPLETE. Many revision control systems have a feature called keyword expansion. This will allow the revision control system to update files with specific information, including the document's revision within the system. If your document has a field that uses the relevant keyword, the revision control system will update it automatically, removing the need for the document's author to do this. Now, the document's author or maintainer doesn't have to update the revision number anywhere in the document. The only problem with this is that files that use compression as part of its format (e.g. modern Microsoft Word XML files or ODF) aren't accessible to this feature. Nor are encrypted files. It works great, though, with the older Microsoft Word *.doc formats2. All modern revision control systems are network-capable, and allow files maintained within them to be referred to by a simple URL (TFS excepted; those URLs are a nightmare. Even worse than SharePoint!). If you are liberal with your document-access policies (e.g. everyone has read-only access), then everyone will become used to seeing documents being passed as links that all look the same as links to tags and other resources in the revision control system. A revision control system doesn't help with the embedding of documents. However, it will make accessing those documents easier if you use links. The revision control system will automatically hide older versions of documents. These older versions will always be available, though, through the revision control system's interface. The value of a revision control system would be lost if you changed the name of a file every time you updated it. In fact, /keeping the file's name the same for as long as its relevant will allow you to derive the full benefits of using a proper revision control system/. The job of a project librarian is made easier as there are fewer locations to keep an eye on. Also, as some tasks can be performed automatically by the revision control system, the librarian's reviews will consequently be shorter. A revision control system will help greatly in making it easy to do things right and hard to do things wrong, but will give little help in developing a framework that you might want to use for that. And, that's it. Thank you for reading. If you think any of my guidelines is flawed, please let me know. My contact details are at the bottom of this page. Also, if you want me to clarify anything, let me know. At some time in the future, I might address some of the other problems with project files and artefacts, like… Spaces and other special characters in file names. Formatting and how stylesheets help impart the information. Addressing the "I just don't see the value of doing this," and other misconceptions around documentation. Why the name of a file doesn't necessarily indicate what's in the file, and the wider consideration that we shouldn't confuse a document and the computer file that contains that document. Footnotes: 1 In my head, a file is a container, and the document is the information within it. For this reason, you'll read sillinesses like "a document's file name" in my writings. 2 I would like to be wrong: if you know of a way that keyword expansion will work in ODF files, especially, please let me know. My contact details are at the end of this page. Documentation and versioning, Part 2 of 2Éibhear, 2015-07-31 08:21:00 IST In part 1 of this formerly two-part, now three-part1, series of posts, I explored what can happen with document versioning if there's little or no discipline. In this part I set out to offer some simple suggestions to make versioning of documents predictable and understandable, which will make the documents themselves more accessible. The following small set of rules on versioning can greatly improve the quality and traceability of your documents. In summary, these are: Use only one versioning system for all your project's artefacts. Use a document properties to record version information Maintain documents in a networked location, and use URLs. No embedded documents Remove older versions out of the way. No version information in file-names. Use a project librarian Make documents easy to get by making them easy to produce properly. The first 5 of these is covered in detail below, and then in part 3 I will discuss the last 3 and how to make things even easier by using a dedicated revisioning tool – i.e. the one your software developers use – for your documents too. Use only one versioning system for all your project's artefacts. This might sound obvious, but it's not always the case in practice. Different contributors to your project will have different understandings of what each designation. Version 0.9 to some is just a version number on a draft document, but to others it's reserved for the version that's to be sent out for approval. FINAL means a completely finished document to me, but some colleagues have used it to say this version is the last one to be published to get the very last approvals _v0.5_JDComments is version 0.5 marked up with comments by John Doe. To me, this is not a new version, though I've seen others regard it as one (i.e. send it around as a version to be reviewed, rather than incorporating the comments into _v0.6). The versioning system you use should be simple, so that all interested people don't have to try to remember loads of different rules. One recommendation is to separate the mechanism you use to distinguish one version of a document from another, and the mechanism you use to identify the stage the document is at. For example: x.1, x.2, etc. denote documents in draft, incrementing with each new version that is published. These will continue incrementing (x.8, x.9, x.10, x.11, … x.19, x.20, … x.99, x.100, etc.) until the document has been fully approved. 1.0 denotes the first fully approved version of the document. 2.0 is the second fully approved version. And so on. If an approved document is to be amended, then the minor number is to be incremented (1.1, 1.2, 1.3, etc.) until that version has been approved (at which point the major number is incremented and the minor reset to 0). The status of the document is represented more clearly, though. A document can only be in DRAFT, FOR APPROVAL or COMPLETE states. Alternative words could be used for COMPLETE, such as APPROVED, FINAL (though, I wouldn't recommend either of those!), LIVE, etc. Using, the x.y notation, if y is not 0, then the document's state is either DRAFT (still in the works) or FOR APPROVAL (author thinks it's complete, but has yet to get important people's agreement). Once a document is COMPLETE, the y value is set to 0 and the x value is increased by 1. There really is no need for it to be more complex than that. In fact, I prefer a simpler arrangement: version numbers are just integers (1, 2, 3, 4, etc.), and the document state is the only indicator of the document's progression. Use a document property – where supported – to store theq document's version information As it makes more than just sense for the version information of a document to be expressed somewhere within the document, one often finds it in multiple locations: title page, page footers, page headers, introductions, etc. If these are each individually typed into the document, then each time the version is to change, it needs to be manually edited in all places in the document where it's expressed. Some people will miss some instances, and others will decide that it doesn't need to be updated until, say, a certain milestone is achieved. Both of these scenarios are problematic. Microsoft Word, LibreOffice Writer, OpenOffice.org Writer and many other document editing utilities allow for the configuration of fields that can be set in the document's properties and then referenced throughout the document's text. If the author updates this "field" or property and then instructs the document to update all references to it, all expressions of the document's version within it will be updated. Maintain the document in a networked location, and use links. Don't let documents be sent around as attachments to e-mails. No matter how hard you try, there is no way to make sure that all relevant people will pull up the correct version of all documents at all times. If, however, you send only a link to the document, then all recipients of your notification will be pull up the linked-to document (if they haven't saved it off somewhere!). In order to reinforce this I often put the following statement in a prominent location of a document: This document is maintained at <documentAddress>. The only official version of this document is at that address. If you are reading this document from some other location, you are advised to retrieve it from the above address in order to ensure that you have the most up-to-date version. In this scenario, copies and printouts of documents are immediately obsolete, not necessarily because the official version is immediately different, but because the copy or printout cannot track any updates to the official version. In addition to this, I would strongly recommend that everyone in the organisation have (at least) read-only access to the location where the document is being maintained without having to raise a specific request for this. This is very important. If there is no compelling reason to restrict access on documents to legitimate members of the organisation, then all documents should be accessible to all users without the need for instance-by-instance granting of permission. It's bad enough if someone has to supply a username and password every time they want to read a document, it's worse when that person has to wait a number of days to be supplied with a username and password. In this case, a number of risks arise: A legitimate reviewer of the document can't review it; Your deliverable is delayed while you await the granting of access; Or your reviewer has to provide comment on an unofficial, obsolete version of the document that had to be e-mailed to them (see above). This latter risk is especially important, as it might seem minor, but without rigorous application of your rules, it is the slippery slope that will make a networked location of the documents pointless. Think open: unless you have a good reason to hide it, you shouldn't allow it to be hidden. Don't embed documents Don't allow the embedding of documents within documents. This may well be a handy way to pass documents around, but it comes with problems. Documents aren't directories. That you can put one or more documents into another doesn't mean that you should. Embedded documents can't be maintained as flexibly as documents in a directory. Changes to embedded documents aren't independently trackable. Many would see a change to an embedded document as not requiring a version increment, but then others would not know that the embedded document has been changed. Comparing different versions of an embedded document, each in a different version of the containing document is, at the very least, a challenge. And, if you're in the habit of passing around links to a document, then there's no need to embed it. Remove older versions away. Don't keep older versions of a document (even the immediately previous version) in the same location as the current version. When someone lands in the directory or folder where the document is maintained, there should only be one version of the document available. This will make it completely clear as to which file should be accessed: there can be only one. If you need to retain older versions, and if you aren't using a revision control system that does this for you (see below), then copy those older documents into a different directory. If that different directory is to be a sub-directory of the document's normal home, then it should be named such that it's clear that live documents don't reside in there. (Call it Archive, previousVersions, Obsolete Documents or something like that.) In part 3 (of 2!), I finish going through my suggestions, and then will discuss one way of helping putting them into place. Footnotes: 1 Dreadful planning. This series initially started out as just 1 post, became a two-parter when I saw that there was more to say, and now it's a three-parter, largely because I've said too much! Documentation and versioning, Part 1 of 2Éibhear, 2015-07-29 20:59:00 IST In all software engineering projects, documentation is critical. This is the first of two1 posts where I discuss my experiences and insights about project documentation – particularly how versions of documents are recorded – offering some simple suggestions for improvements that you might not yet have considered. Documentation serves to record things like why you're doing what you're doing, how you are doing it and how to pick up from where you left off. I've seen more than a few projects fall into big trouble – or cause serious post-implementation support problems – because of lax attitudes to documentation rigour. Most often, documentation best serves a project if the following is understood before-hand: What documents will be produced; When will they be produced; What benefit will they have; Who will review and/or approve them; What are the pre-requisites for each. Until there has been enough exposure to the expected documents, projects tend to worry about these matters and the impacts they will have on the success of each project2. One of the core the Problem(s): document versioning The aspect of documentation that – to my view – causes the biggest problems is versioning of the documents. Versioning of technical files, like source code files, seems not to be a challenge. For the technical staff, it's somewhat ingrained. For the non-technical staff, it's not massively important. If you agree with me, however, that the following two assumptions are correct, then we need to be as rigorous with our document versioning as we are with our source code files: A project's documentation is as important to the success of the project as all other artefacts, like source code. Project documentation doesn't magically appear out of nowhere: it's developed iteratively just like any other aspect of a successful project. Traditionally, I have required the same revisioning regime for our documents as for our code files. However, not all documentation can be maintained in this way, and not all projects operate in this way (even if it's technically feasible). Very often, revision control of documents is done in an ad-hoc manner. Also, the tools being used are not designed for the task (e.g. going back through old e-mails), are not up to the task (e.g. versioning by giving files different names) or don't integrate well with the revisioning tools used by the rest of the project (e.g. Microsoft SharePoint – unless, of course, you're using SharePoint for versioning of the rest of the project, in which case I suggest you stop reading this: your problems lie elsewhere…). And then there's the problem of consistency: in many environments, documents are versioned using the scheme that the author at that time thinks is appropriate. When you have many authors, each using a different scheme, each deciding on a case-by-case basis what his/her scheme is, you can get the following: 0.1 DRAFT 0.2 0.5 FINAL 1.0 FINAL Updated FINAL DRAFT – For approval FINAL FINAL 0.9 … which might describe the progression of just one document! And then there's the problem of internal consistency: I've often seen a single document with up to 3 different versions expressed in it: in the document's file name, in the title page of the document, and in the footer (or header, or both) of each page of the document. There are many who have had perfectly good documents rejected by me because they neglected to update the version information in all places in the document. In part two of this two-parter, I'll set out a small set of guidelines that would address the significant issues around document versioning. Once I have it published, I'll update this post with a link to it. Update: it's here. Footnotes: 1 Now three! 2 Though, it helps a lot if when project regards stability and quality as highly as time-to-delivery and costs Knowing more about the herdÉibhear, 2015-06-17 20:08:00 IST On the 11th June, it was announced that a new case of BSE had probably been found in Ireland. This is, of course, disappointing; the week before Ireland was declared to have a "negligible risk" status as regards BSE. Ireland's status is probably going to be raised to "controlled risk", which happens to be the risk status it had when the US and some other important markets were opened to Irish beef in the last few months. In an article in the Irish Times the following day, we heard from the minister for agriculture, Simon Coveney, what was being done to determine the source of the infection. In discussing the rigour of the system for tracking and monitoring cattle in Ireland, Mr. Coveney is quoted as follows: He said Ireland "probably knows more about our bovine herd than we do about our people" and there was a "very, very detailed, credible system" in place for monitoring animals. OK. So he's saying that, as all details of all cattle are entered into a centralised database, we can know everything about the whole herd in Ireland (somewhere around 6,000,000 cattle), including, for example, where they were at any particular point in time. And that it's remarkable that we don't know this much information about the people in Ireland. While he is not suggesting that it's regrettable that we know more about cattle than people, it's staggering that a politician in a democratic country would make such a comment. In a republican democracy, it's supposed to work the other way 'round. To a republican democracy, it is repugnant for the government to know anything about any person except what is needed to provide a service to that person. That a government minister would say something like this lends validity to the growing desires of so-called democratic governments to infringe on individual's rights to privacy and free association.