Tag: SDK

bookmark_borderWhat not to do

Posted on

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?

bookmark_borderThe Presumption of Common Sense

Posted on

If there is one phrase which should set off alarms in the mind of a technical writer it’s when a developer says “Ohhh but they wouldn’t use it like that…”.

Because, as I’m sure you all know, they will.

I am currently working with a few people to try and pull together a solid set of product usage recommendations. We provide an SDK and a feature rich application built using our own technology, and that application is extended and configured for specific uses. There are plenty of hook points in there and, for the most part, usage follows accepted patterns. However there is always the time when a certain component is bent and twisted and used in a way we hadn’t expected and it’s these instances that we are trying to understand and capture.

We get a view of them by exploring edge cases when testing, but it occurred to me that there is still one thing that can catch us out. Our old nemesis, ‘presumption’ (which is usually coupled with it’s friend ‘common sense’).

So now I’m on red alert for any statements which are based on presumption. Sometimes they are right, but it’s the times when they are wrong that we need to explore them, capture them and help our customers by giving them some frame of acceptable usage. It’s not an exact science, but even just pausing to have those short conversations seems to be helping.

bookmark_borderPlanning your deliverables

Posted on

I don’t like making presumptions, something that I learned early on in my technical writing career, but I am going to presume that anyone who reads this knows that they should be planning what content they produce before they start writing. You do, right?

A basic information plan will include knowledge about the audience, the main areas of the information that need to be covered for the project/release, as well as outlining the purpose of the documentation and any media and design considerations. Finally you’ll most likely provide a definitive list of deliverables, be they printed documents, PDFs or online help.

It’s this last area that I’m currently working on.

Our product has undergone some exciting changes, and the previous set of documentation was both very document-centric and , in my opinion, badly structured. We are shifting more towards a ‘traditional’ SDK approach and as such a lot of the existing documentation needs to be adapted accordingly.

Thankfully it’s largely an exercise in restructuring the documentation rather than completely rewriting anything, but it still warrants discussion with the audience as to how best to present the information they require. In that respect I’m lucky to have direct access to a representative portion of the intended audience as the bulk of the audience will be our own staff.

The functionality available in our development kit is broken into sections, with the documentation split along similar lines, and as such whilst the information in the current documentation is fine, it no longer makes sense to have it structured that way. Breaking down all of the documentation into smaller, more manageable chunks, before deciding how best to piece them back together is the current focus.

Thankfully, in preparation for our move towards single source, we had already audited our content and so, if nothing else, I have all the discrete sections of each of the current documents already list in a ‘management friendly’ spreadsheet.

So, with a bit of manipulation I can easily mockup a sample set of information topics, and then figure out how best to present them to the audience, be it PDF, online help, or via the web.

Once we’ve got a good idea of our final deliverables, I’ll run them past a sample of the intended audience to make sure they are both what is required and to set the expectation of what we are, and aren’t, delivering. Hopefully, gaining buy-in to our plan as early as possible will mean the information we provided is better received and may even start further discusssions around future improvements.

bookmark_borderWhat do you write?

Posted on

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.