31 July 2020

Hong Kong: Is it still One Country, Two Systems?

Following the handover of Hong Kong to China in 1997, the principle of one country, two systems was used to describe the method of governance of this former UK colony. In brief, it allows Hong Kong to be part of China, yet retain its own economic and administrative system. Significantly it also meant Hong Kong could have its own government, legal system, and trade relations with other countries, that are independent of the mainland.

Negotiations on the handover of Hong Kong from the UK to China, agreed that the principle of one country, two systems should exist for 50 years. Unfortunately, it has never been defined what should happen once this agreement expires. In effect the issue was postponed for someone else to deal with before 2047.

Roll the clock forward, and we're in a very different place politically. Former Chinese premier Deng Xiaoping didn't even live to see the implementation of the handover he negotiated. The last Hong Kong Governor, Chris Patten, has been vocal about recent issues affecting Hong Kong, but hasn't much political power to do anything about it. By comparison, China's economic and political power has increased immeasurably, to the point where it feels confident to take on major world powers.

It would be naive to expect China to accept the Hong Kong status quo in perpetuity. It was always likely the motherland would erode the freedoms of Hong Kong citizens. China has a long history of dealing with dissenting voices in a harsh manner. Amnesty International's Annual Report highlights a long history of detention and imprisonment of those who dare to speak up against injustice. The use of torture is widespread, and freedom of expression is suppressed. 

Hong Kong citizens may not suffer in quite the same way as those of Tibet, Beijing or Shanghai, but how long will it remain so. The signs are that China is flexing its muscle and gradually eroding the principle agreed prior to the 1997 handover. Admittedly residents can still protest, and there is a degree of political autonomy in the Hong Kong legislator, but the recent implementation of new security laws aims to undermine this.

The new laws are just one part of a concerted effort by China to crack down on dissent. The BBC's China Correspondent Stephen McDonell recently highlighted just what is going on behind the scenes. It's well worth listening to.

In the video Stephen points out how:
  • Chinese state security agents have set up camp inside Hong Hong. In another report he's highlighted their new state of the art building. These agents are operating above the laws of Hong Kong. They can't be stopped or questioned, even by the Hong Kong Police Force.
  • The Hong Kong courts have judges chosen by Hong Kong's Carrie Lam, who herself was chosen by Beijing, meaning the chances of a fair trial are diminished.
  • Some books have been removed from libraries. It has also been reported elsewhere how book shops harassed if they sell anything deemed to be too sensitive.
Perhaps even more concerning is what the new security laws could mean not only for Hong Kong residents, but for everyone throughout the world. It aims to stop the singing of certain political songs, chanting certain slogans, and carrying banners or wearing clothing bearing specific words. It most certainly prevents calls for greater autonomy or Hong Kong independence from China.

All of this is aimed at suppressing the increasingly violent and disruptive protests we've seen in Hong Kong recently. But the wording of the new laws are vague enough to apply to just about anyone doing anything that Beijing doesn't like. If a pro-democracy member of Hong Kong legislator tries to speak up against the laws, could they be arrested? Could I be arrested if I travel to Hong Kong, just for writing this blog post?

I've visited Hong Hong several times both before and after 1997. It is a wonderful, vibrant city that everyone should visit at least once. The one constant there is change, but with that comes a cost. By implementing these new security laws, China is trying to keep a lid on dissent whilst allowing Hong Kong a measure of freedom not allowed by other Chinese mainland regions. The problem it and the world faces, is that cracking down on dissent increases the depth of injustice.

Sooner or later something will have to give. Perhaps if the long term future of Hong Kong hadn't been kicked into the political long grass prior to 1997, we wouldn't be in this position now. By implementing this law, China has seized an opportunity to impose its will on the people of Hong Kong. It figures the political and diplomatic cost of doing so, is less than if the very fabric of Hong Kong life significantly changes. It just may be right.

29 July 2020

Getting Feedback on your Technical Documentation

A question that is often asked of Technical Writers is, "How useful is your documentation?". All too often the question results in a shrug of the shoulders and an "I don't know" answer. That's a shame, as it is only by understanding how our users use our content, and the feedback we get from that, that we can truly answer that question. The problem is, how can you get that feedback.

There's really no substitute than a face to face conversation with your users. Admittedly it is time consuming and expensive, but it can lead to a wealth of valuable information. Your skill at asking a Product Manager questions that unearth useful nuggets about functionality in a future release, can just as easily be applied to asking open and probing questions to users about their use of your "product".

The problem is that most Technical Communication departments are "protected" from meeting customers by a combination of budget, organizational set-up, and lack of a cohesive content strategy. This makes the chances of most Technical Writers speaking to their users near impossible. So what other options are there?

If you can't get out to your users, and you must never give up trying, the answer can come through the use of technology. Both the main players in the technical communication tool space offer solutions that provide statistics on your content's use.
  • Adobe RoboHelp Server has been around for years, but has recently undergone a major rewrite. RoboHelp Server requires a Java runtime environment (e.g. JRE or Apache Tomcat) and a database (e.g. Oracle or SQL Server) but the installation and setup is very easy. When I tried, it took me little more than 30 minutes See the Adobe RoboHelp Server System Requirements page for full details.
  • Madcap Central is the newer kid on the block and offers similar functionality. Unlike Adobe's offering, Central doesn't rely on external software or databases. You just need a browser and an internet connection. Instead, it has partnered with Microsoft Azure to host your content. See the Madcap Central System Requirements page for full details.
Both of these offering have very similar functionality. Their series of reports display statistical data of the number of page visits, search terms used, search terms used that returned no results, context sensitive help calls, etc. All very useful, but the offerings aren't the golden bullet you may expect. Here's why:
  • They only work with specific content. Adobe RoboHelp Server only works with Responsive HTML output. Madcap Central also has limitations with the Flare targets that can be published to Central, but also offers content not being authored in Flare to be hosted.
  • The reports offered by both solutions are fairly basic. For example, they don't allow much in the way of customization or filtering.
  • Statistics on their own provide only part of the story. It requires time and effort to analyze the results and action change. For example, repeated context sensitive help calls from a dialog could mean there's a need for a UI or copy change.
There are other analytics offerings. Google Analytics offers a wide range of statistical information, although it isn't tailored specifically to the technical communication industry. It requires you to add a tracking code to your content, and depending on the content size and usage, may require you to pay Google for the privilege of using it.

The takeaway is that getting feedback isn't easy, and even when you get it, it needs additional time and effort to use the data effectively. It may require buy in from other teams. For example, if the UI needs changing. Get the process right, and you've a great resource at your disposal.

Let me end with a tale from my past. 

I once had a manager who just wanted to know how many hits the documentation got, and the more the merrier. He used these statistics to justify our existence. He wasn't interested in the analysis behind the statistics. I could have spent all day pressing the F5 key to boost the stats, and he'd have been happy. The end result of this, is that I didn't stay long at that gig!

21 July 2020

The Battle of the TechComm Giants

A little under two months ago, a fairly nondescript email arrived in my inbox from Adobe. It advertised a "Special Event" on 15th July, and urged me to register for it. There were precious few details, but as I sarcastically tweeted at the time it was pretty obvious a new release was on the cards.
Yes the release of Adobe's Technical Communication Suite 2020, complete with updates to RoboHelp, FrameMaker, and Adobe Experience Manager, has arrived. The "special event" that officially announced the release involved a mixture of Adobe staff and industry experts and covered a whole six hours of sessions!

It would be wrong to say the "special event" covered one topic. It was a series of sessions covering various topics related to Adobe's Technical Communication Suite. I'll cover the major points of these in a series of future blog posts, but it was what was happening alongside this event that proved most intriguing.

The long lead time to the event, together with the pretty sparse details of what it would cover until the week before, gave Adobe's competitors little scope for a spoiler event. That didn't stop Madcap Software from organizing an event alongside Adobe's. Although only 90 minutes long, its timing was aimed at getting a peak audience from territories right across the globe.

There's history between Adobe and Madcap, with the later being founded by ex-RoboHelp employees after the product was sunset by Macromedia. Adobe later bought Macromedia and reversed that decision, but not before Flare had a foothold on the market. Throw in Madcap's disruptive marketing approach, and you have a real battle on your hands.

Arguably having two vendors having to compete for our custom is positive. It is certainly true that if one vendor makes a move by providing functionality the other hasn't, the other has to follow suit in a future release. Madcap often seem to take the lead with this approach, causing Adobe to play catch-up, but Adobe can also play the same game. As a smaller and leaner company, Madcap are better positioned to make such moves. Adobe on the other hand have shown their commitment to the market by continuing to develop their product portfolio. This is to be admired from a colossus like Adobe.

Interestingly I notice Adobe seems to have addressed the SEO on their products. For example searching for "RoboHelp" in the past tended to return "Madcap Flare", "Paligo" or some other Madcap content in the top set of results. You had to look down past the first few results to see any content on Adobe products. That appears no longer to be true.

Reading between the lines, Adobe think they have a product that can take on and win against the young upstarts at Madcap. They've certainly lost ground more recently, so it will be interesting to see how the battle of the technical communication giants pans out.

23 June 2020

Is there a difference between a Resume and CV?

As a UK Technical Writer who has worked for various American companies, I'm well versed in the variances between UK and US English. I've lost count of the conversations I've heard about whether to spell it "enrol" with one or two Ls, or whether dialog should have a "ue" on the end. So when it comes to whether I call my Curriculum Vitae a "CV" or "Resume", it depends on the audience I'm speaking to.

Curriculum Vitae means quite literally "course of life". In the professional context, it should include anything relevant to the job you're after. For example, educational qualifications, awards, previous employment, achievements. There's little debate about that, but what level of detail should this include? Various online definitions don't help, with mentions of "summary" or "detail" depending on which one you look at.

In my mind at least, there is no difference between a CV and a resume. They are one and the same thing. The nouns are just another example of localisation, sorry localization :-) But a conversation held as part of today's #TechCommTea meetup shed new light on this grossly incorrect assertion.

In India job applicants are increasingly asked to provide a Resume when applying for jobs. This mirrors many of the characteristics folk in Europe and the US recognise / recognize as their CV / Resume. In effect a two page summary of the professional journey and expertise.

Anyone who's written their CV / Resume can testify that keeping the content to two pages can be difficult, especially if you've had several jobs. After all you want to ensure you include all your achievements from each position, and using a smaller font isn't the panacea you crave. 

So what is the answer?

In India at least, the answer is to have a Resume and CV. The resume is the summary of your experience and skill set, should not be more than two pages, and is what is submitted with your application. If successful, you are then asked for your CV. This is a much more detailed document, often including the projects you worked on and tools used at each of your previous employers.

This two tier form of Resume / CV is also part of a very different recruitment process. Whilst most employers in the US and Europe wouldn't normally expect a candidate to attend more than three interviews, it is common in India for candidates to frequently attend 6+ interview rounds. The worst example I've heard is someone going through 26 interview rounds!

Such examples may be rare, but highlights the regional differences in the recruiting process around the globe. It is a balance between the demand for a role versus the number of available candidates. Most job candidates in the US or UK wouldn't apply for a position if faced with a round of 10 or so interviews, but in other parts of the world it is a way of life. Neither would many UK or US employers deem it worthwhile to have such a long recruitment timeline.

I remember a previous role where I had to travel to different parts of the UK. It was an eye opener from a language perspective as I encountered many regional language differences. I remember one specific one was "sausage roll". In my mind it was clear it was either sausage meat surrounded by puff pastry, or a bread roll with a sliced sausage inside it. In some parts of the UK the latter was a sausage cobb if it was a hard roll, or a sausage bap if a soft roll. And I'm still unclear what the difference is between a "bun" and a "cobb" or "bap"!  

Who's right? As Mark Twain's humourous / humorous quote illustrates, the answer is who has the power and influence to say they're correct.

11 June 2020

Is removing statues the answer?

This weekend saw demonstrations throughout the UK in the aftermath of George Floyd's death in Minneapolis last month. Most protests were peaceful, but a minority of protesters attacked the police or damaged property. Among the property attacked were symbols statues of people from the UK's colonial past. 

One target was the statue of Edward Colston in Bristol, a city that benefited greatly from his wealth. Colston was a slave trader, responsible for transporting approximately 80,000 men, women, and children from Africa to the Americas in the late 17th century. His "cargo" were held in cramped and unsanitary conditions for the voyage, and many didn't survive the crossing. During the Bristol demonstration, his statue was ripped from its plinth, and unceremoniously dumped in the harbour.

There have been similar actions against statues elsewhere going back several years. For example, many have called for statues of Cecil Rhodes to be removed for decades. Similarly, many in the US want statues of Robert E Lee removed. Belgians have called for statues of King Leopold II to be removed because of their country's colonial past in Africa. In the UK even statues of Winston Churchill have been targeted.

I don't condone direct action against property. Action like that taken in Bristol is dangerous. But putting that aside, is it really an effective method of righting the wrong? I don't disagree with the sentiment, just question the method used to draw attention to the injustice.

Damaging or destroying a statue raises the question of where you draw the line. Is a statue of Margaret Thatcher acceptable after her treatment of the unions and particularly the miners? What about Tony Blair and his support for an invasion of Iraq? It is fair to say that you could find something to disagree with every public figure if you look hard enough. Such individuals are rarely black and white. Even Edward Colston had a philanthropic side, which saw him fund alms houses, hospitals, and schools in Bristol.

I'd prefer to focus on educating people on the rights and wrongs of public figures. Yes looking at the facts with 21st century eyes, it is clear to see the wrongs. So let's use the statues to educate of where things went wrong, and what we can do to put things right. Perhaps add a plague to the front of a statue summarizing the person's legacy.

Some cities have removed certain statues and put them in museums. Perhaps this is the answer going forward. Museums are educational establishments, and if done correctly they could educate people on the good and bad of what the individual did.

But even that appears to erase history. It is often said that history is written by the victor. Perhaps it is time this changed. Removing our history from public view seems an extreme step. Removing statues of people considered unpopular in 21st century popular culture and putting them behind doors few will enter, seems like a retrograde step. Let's call out injustice where we see it, but having a visible reminder of how man can be cruel to others can prevent it occurring again.