Tag: <span>API</span>

Working in a team that isn’t heavily invested in documenting requirements and specifications (we usually have a starting set of such things but these soon fall out of step as development evolves) makes it a challenge to know both what is being added to the product and whether it needs to be documented.

The development teams recently adopted JIRA and whilst the additional information helps I fear it may give us a bigger problem. As we will (should?) finally have a clear picture of everything being added to the product, will it be too much for us to handle?

At present the Publications team have two very large products, with a complex API and code base which is all evolving and which needs to be documented. We cover a mix of SDK style documentation, reference information as well as procedure based topics and many conceptual pieces. We don’t document all of the product at the moment but it’s fast becoming apparent that deciding what NOT to do will be a vital skill as we move forward.

We can’t, and shouldn’t, document everything but a firm focus on making sure we are providing the most value (bang per buck!) helps us make better decisions about what we can ignore, and what our customers really need.

How do you cope with the ever increasing pace of development? What don’t you do?


It’s going to be a big year for us, both as a company and as a team. We have grand and achievable plans for the product which will mean the working processes for the Publications team will need to change for, as well as multiple streams of work with their own staggered release dates for the product, we are also restructuring our entire information set to improve ‘findability’.

Which immediately prompts a question, how do you improve ‘findability’?

The simple answer is would be ‘in as many ways as possible’ as there is no silver bullet. What may work for some, won’t work for others. However we have to start somewhere and the first thing we can do is restructure the architecture of our information, slimming down the content where possible with an eye to adding new formats of information.

We have already successfully piloted some new formats of information and will continue to roll more of those out for different areas of the product (in essence, these new documents are a high level overview of all the levels of an area of the product, from concept and usage to API implementation), and the signs are that the restructure will go a long way to meeting the needs of our customers.

Having been lucky enough to speak directly to some customers in the latter half of last year, I know that we are on the right path. The challenge will be to keep moving things forward amidst everything else. It’s going to be a busy year and already the analogy is one of a juggler who is keeping things in the air… for now!


Next week the first of two new recruits joins our team. Both are graduates and whilst neither graduated from a Technical Writing based course they both have a good mix of skills, coming to the position through different routes. It’ll be a challenge for them, and a challenge for us, to integrate them to the team smoothly and successfully. I’m sure they will both do well, but to give them the best chance I’m preparing a few weeks of training for them, in various aspects of the job.

I’m trying to anticipate what they need to know, and when they need to know it, and whilst I’m very wary of letting my own experience get in the way it does mirror what they will be going through as my route into this profession was via an Electronic Engineering course, and I too had no experience in Technical Writing.

Training on our authoring tool (Author-it) is straightforward enough, and we will be mentoring each of the recruits as well so day to day questions we can handle.

We will likely use the IBM book “Developing Quality Technical Information” to provide a grounding in the basics of Technical Writing, along with an eLearning book titled Basics of Technical Writing that we purchased from CherryLeaf a few years ago.

They will have to learn how we do things, our specific processes, and learn how the overall Development team works so they understand where they fit, and they will receive a series of training exercises to complete before they take our product training course. On top of all that they will have a week long company Induction.

I’m a great believer in people learning by doing, so I’m planning a set of small tasks which will be checked and reviewed, and which will ultimately find their way into our documentation set.

Beyond that, I’ll be looking for them to ask questions, try things, make mistakes and learn from them, and then ask more questions. This industry is too varied to try and learn everything at once, and ultimately it’s down to them to decide what areas they want to push into… user experience? content design? API information? Who knows.

I do know it’s a challenge, for everyone involved, and that’s one of the things we, as a company, do best. There is a saying we have about being two feet outside your comfort zone, that’s where you learn best, that’s where you grow and start to understand your capabilities, so we will see how our recruits get on!

For me it’s doubly exciting as this is only the second time I’ve taken on graduates. I learned a lot the last time, both about how to train them and about my own foibles and attitudes to my profession so I’m brushing up my own knowledge to make sure I, and the rest of the team, give them the best change they have. In saying that, the first time I did this I was in my first ‘senior’ position, that was 10 years ago so hopefully by now I’ve gained a little bit more experience!

After all, you learn something new every day.

Have you brought a graduate into your team? Or are you involved in training or mentoring new recruits? If you have any suggestions I’d love to hear them.


Most of my experience is based around software documentation. Whilst there are several levels to this, from task oriented User Guides through to highly technical API/SDK documentation, they tend to follow similar patterns making it easy for me to take my experience and apply it to new challenges.

I’ve also been involved in writing up procedures and guidelines as part of an ISO quality system, a little whitepaper style writing, and even the odd product brochure. All of which require a slightly different approach but the same grounding in the basics of understanding the audience.

However I’m aware that there are many other forms of technical writing, and I’m curious to find out what everyone else does? Do you write documentation for hardware products? Do you write proposals? Procedures?

Ultimately I’m starting to look at other areas of our profession to see if there are any good things that I can re-use where I am. If you have a moment, I’d love to hear what your main writing focus is, let me know in the comments.


My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

I recall once being asked to breakdown all the skills required to be a Technical Writer, and then to provide a list of daily work tasks. The list of skills was to be used as part of a skills/training matrix, and the work tasks were to be mapped to a timesheet system.

At first I concentrated solely on the Technical Writers role, but even then you need to wear a number of hats; researcher, analyst, information architect, publisher, indexer, illustrator, proof-reader, editor… ohh and writer. All of those are unique job roles in some places yet, as a Technical Writer, you need to be able to successfully take on those roles to some degree. In most software companies a large part of the job is learning the new features, and as you have access to early builds, you are frequently also playing the part of ad-hoc tester. Admittedly you are usually only testing one scenario, and that scenario is the happy path that will be documented, but a bug is a bug and that means being able to identify one, discuss it with a tester or developer, or both, and why not log it as well?

If you are documenting an API or developer toolkit then, in those instances, you frequently don the cap of novice developer, asking the questions you expect them to ask, before switching caps to presume the role of an experienced developer and wondering if the information you are providing is too simple for them to use or if, perhaps, the structure of the information needs altered.

You need to be able to talk to developers and so you need to know a little about whichever code language they are working with, that way when they mention methods, you can ask whether they mean static or instance.

None of these skills/roles are the core part of a Technical Writers job, but simply additional strings to your bow. The more you know about everything, the more value you can add, so long as you don’t let that detract from your core responsibility, to provide documentation. However, the more you know about everything, the better that documentation will be and the higher your value will soar.

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).


Comments closed

LinkedIn API “Opportunity” – sounds useful but hope it doesn’t go the way of other sites with a multitude of useless add-ons. LinkedIn needs to remember that professionals want a professional product. That’s why I’ve dumped Facebook, too much dross!


Comments closed

A day earlier than planned but glad that this is now out in the open. Cross-posted on Scottish Blogs, with a similar post on BritBlog.

BritBlog and Scottish Blogs Join Forces
Some of you may be familiar with the British Blog Directory, a site similar to Scottish Blogs that focuses on (as the name suggests) British bloggers. Mark, who runs the site, and I have been in discussion for some time and we are both pleased to announce that we will soon be joining forces.

The reasoning is simple: combining resources means we can offer our members (and web users at large) more.

Because of the group-focus that the new BritBlog will have, existing members of Scottish Blogs will become part of a similar Scottish Blogs group. With the Scottish Blogs website remaining the focus for that group.

Why join forces?
As BritBlog continues to grow and the number of blogs in Scotland and across Britain rises, the opportunity to offer a better web site and better set of resources increases. There has been a lot of work going on in the background, all aimed at bringing better functionality and more features to the BritBlog web site, so here, for your comments, are our current plans for the future of BritBlog.

The main goals are to improve the community feel of the site, to allow special interest groups and communities to form, and to develop more resources for British Bloggers.

New features will include:

  • A focus on groups and communities – enhanced features to allow communities of bloggers with similar interests or geography to form and grow.
  • RSS feeds galore – allowing you to keep up to date with new blogs and posts from our members. Feeds will be available for specific groups.
  • Improved searching and blog classifications – to make it easier to find blogs that may be of interest to you.
  • Multiple blogs can be registered per user.
  • An open database – developers will be able to integrate BritBlog with their own projects using our web services API.

As you can see, there will be lots going on.

So when is this all going to happen?
Timescales are still to be confirmed, and there’s a lot of planning to do and code to write. We’ll be re-writing the whole site from the ground up, so don’t expect to see too many obvious changes straight away!

Needless to say there will be a lot more on this as the idea progresses but we’d appreciate your thoughts, positive and negative, and any other questions that spring to mind.

My reasoning is simple. I don’t have the technical knowledge to take Scottish Blogs forward any further, but I do have a good understanding of blogging and think the new site will be beneficial in connecting people. Interesting times lie ahead and Mark and I would really appreciate your thoughts.

So, leave your questions, thoughts and ideas in the comments. Mark and I will be collating them all from our sites and I’ll post a response/update sometime next week. Remember, this site will only be successful if people use it.


Comments closed

An open letter to SixApart.

Dear TypeKey,

You came promising much, the chance to be able to track myself across the comment boxes of the land, the opportunity to build relations and create networks. A unique insight to my self, my habits and passions. Ohh how you have failed me.

Maybe I expected too much, maybe I didn’t really ‘get’ what you are all about, and if that is the case then accept my apologies and my excuses for my apathy. Mind you, you can’t even be bothered to remember me for longer than two weeks so it’s not like you are trying so hard yourself.

Do you treat others this way? Or have you stopped caring altogether? I once thought of you as a saviour, a guiding light, constant and unwavering, through the maze of commenting systems and blogging platforms. Little did I realise you were just an optical illusion, a dazzling artefact that flattered to deceive.

Don’t worry I’ll keep in touch, I’m not abandoning you, I still care. I just wanted to write to make sure you realised my disappointment.

Yours in apathy,

Gordon McLean

For those who are currently wondering what the chuff I’m waffling on about (and let’s be honest, it’s not the first time):

“TypeKey is a free, open system providing you a central identity for posting comments on weblogs and logging into other websites.”

So, to my mind, what this service could (should) do is, for every website I visit that is TypeKey enabled, allow me to generate a list of all the comments I’ve ever made. Alas that doesn’t seem to be the reasoning.

But why not? It’s the one thing ‘missing’ in most blogging stats, and the hardest one to crack, yet there is an API available so why hasn’t anyone risen to this challenge? Are there pitfalls I can’t see? Why isn’t there a tool to do this? There are a plethora of online tools, with more and more focus on blogs then surely this is a ‘must-have’ item??

I’m confused, let-down and wondering if I should take up the baton myself. Except I’m kinda busy at the moment…

Ohhh and apologies for the title, it’s supposed to be a take on the Great White Hope but not sure it works too well.

Blogging Work

Comments closed