What not to do

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?


  1. I’d do three things:
    – Talk to representatives from your target audience to get a clearer picture of what they need from you (What are their main pain points? When do they read what you write and why?)
    – Think about legal aspects: Are there some deliverables you can’t do without from a legal point of view?
    – Take a close look at the procedure-based topics you document and see whether they are all necessary. (This means thinking again about your target group(s) and their level of knowledge.) Of course, I don’t know your documentation, but this is often an area where you can do something.

Comments are closed.