How to write a kick-ass technical narrative

Innovative

This is the best bit, the one you’ve all been waiting for…how to write a kick-ass technical narrative. By now, know how to nail your technical narrative before you begin writing it and assembling the skeleton structure of your narrative, now, let’s flesh out the skeleton of your narrative to create something HMRC will actually want to read.

Typically, the technical narrative explains your projects/features/challenges you encountered throughout the R&D process. Think of it like the blueprint for showing HMRC exactly what you were up against and how you made progress with your projects for your the years you are claiming for.

Remember: approach this from a technical viewpoint, not a managerial one.

As mentioned previously, the technical narrative is a document that explains the complexity of your project to HMRC. It needs to be constructed from a technical viewpoint (as opposed to a managerial one) and focus on the technical obstacles that were overcome – as opposed to focusing on the process. HMRC want to see you demonstrate how your work was technical complex so give ‘em hell … show how hard you worked and wrangled out a solution for your project – usually, the trickier a project was, the more likely it was that it was R&D.

Keep it simple: 1-3 projects will suffice

HMRC will receive thousands of these applications every single year. As Mark Twain quipped: “sorry for the long letter, I didn’t have time to write a short one”. This doesn’t mean you write a sentence or two about your R&D technical projects but the good length of a technical narrative is 2-5 pages of A4, encompassing 1-3 technical projects. Focus on the key elements of your technical narrative, such as the major challenges and features.

Crucially: marry up the technical to the financial data.

Naturally, you’ll also want to put your best foot forward, so when picking which projects to present to HMRC, be sure to pick the ones that are most R&D-like. Also (and this may go without saying), the claim will consist of the technical data and the financial data. Be sure to pick the R&D projects which you are claiming for, otherwise HMRC may be slightly confused if you are talking about one project in the technical narrative and see no evidence of it in the financial section of your claim!

If these blogs haven’t provided you with enough breadcrumbs to navigate the technical narrative maze, here is an example, based on one of GrantTree founders’ earlier businesses, Woobius. It’s worth noting that we would consider this a tech data collection of extremely good quality. The output from this stage doesn’t have to be to this standard, but it gives an example of what to aim for.

——

Sample Technical Narrative: (constructed from the technical data gathered earlier)

Leadership and role of Woobius

Even on relatively small construction projects, there might be more than twenty independent companies collaborating over a long period. Architects, engineers, surveyors and contractors have to exchange drawings and figures which are then repeatedly revised and corrected over the course of the project. The coming together of such a diverse group of people on a critical project can be the cause of very costly mistakes if there isn’t a clear and easy way for the different parties to share information. Once a building is under way, any mistakes made during planning can result in structures having to be removed or remade and arguments between the parties that can end in the courtroom.

While large construction companies are well served by bespoke project management software made by large software vendors at a high markup, the rest of the industry has to make do with off-the-shelf, general-purpose project management tools not made specifically for architects or small-scale engineers.

Woobius was founded to level the playing field, providing small players in the construction industry with revolutionary collaboration tools designed specifically for architects. With Woobius’ tools, surveyors and architects can concurrently work on hundreds of drawings and documents in real-time, making collaboration easier and costly mistakes less likely.

Experienced architect Bob Leung created the company in 2007 with serial entrepreneur Daniel Tenner. Since then, through word-of-mouth alone, the company has grown from 15 initial test users to over 2,500 users working on over 100 projects in 27 countries. The early success of the company has been acknowledged with its winning ‘One to Watch’ and ‘Best Mobile Product’ gongs at the Construction Computing Awards.

Claimed technological advances

On a typical construction project, twenty or more different parties in different locations will be working on hundreds, maybe thousands, of large PDF documents containing detailed plan drawings. Each drawing is likely to be revised many times by different parties, sometimes concurrently. As a result, to avoid mistakes and overriding others’ changes, architects and planners need software that immediately shows other parties’ changes to drawings and that leaves an audit trail so that everyone knows who made what change when.

Over FY13/14, Woobius focussed its research efforts on building the first web app for small-scale projects that would meet this need. In particular, the team aimed to develop a bespoke architecture in which the frontend and backend would be exchanging data regularly while the app was running to ensure that any user changes, such as updating a drawing or creating a new project folder, would be immediately reflected in the view for all users. To this end, the team planned to build a backend with the Ruby-on-Rails web framework and a MySQL database that would interact with a bespoke front-end built with the Adobe Flex app framework.

To ensure that data was shared quickly and efficiently between the front and backend, the team was forced to develop its own communications protocol. While off-the-shelf technology, such as RubyAMF, existed to allow a Ruby backend to share data with a Flex frontend, the team found that RubyAMF was not fast enough to ensure that data changes were immediately reflected in the GUI for all users. The team consequently felt compelled to create its own encoder that would convert data to the Action Message Format (AMF) necessary to share data with a Flex frontend.

To check for user changes, the team aimed to build its own synchronisation layer that would check regularly for changes to the database so that all other users could see immediately what had been changed. The team planned to engineer a solution in which the frontend would make requests every few seconds to the server for very small text files that would contain a timestamp of when the relevant project was last changed. If the timestamp changed, the frontend could then make changes to the project based on what parts of the project had been altered. The team had initially considered using off-the-shelf solutions from Adobe to manage these checks between server and frontend. However, the team was forced to build its own solution when it became clear that so many regular requests to the server from so many users would place too great demands on the server and hence would not scale.

The expected outcome of these technological innovations was a new software tool that would provide architects underserved by the software market with a bespoke, easy-to-use tool that would aid collaboration and make misunderstandings and costly mistakes among stakeholders much less likely.

Technological uncertainties and how they were overcome

One of the major selling points of the proposed tool was the promise that stakeholders on a project would always see the latest version of a project folder with there being no risk of one person’s overriding the changes of another. The consequent overriding uncertainty of the project was then how to guarantee that any changes made would immediately be reflected in the frontend for all users. This was challenging because it quickly became clear to the team that the off-the-shelf technology that promised to enable live updates of information was very slow and not scalable.

For instance, the team initially integrated the open-source RubyAMF library to convert Ruby objects representing project information into AMF data that could be rendered by the Flex frontend. The team quickly found that even for small projects the conversion of the project tree into AMF format was taking up to two seconds, which was intolerably slow and demanding on the servers. On examination of the RubyAMF source code, it quickly became clear that the library was simply inefficient and poorly designed. The team therefore set about designing its own AMF encoder from scratch, using a test-driven development methodology. Redesigning a popular open-source project from scratch was a highly non-trivial task that would have challenged any domain expert. The team consequently took as its guide the Python encoder PyAMF, whose test suite was extensive. On testing, the team found that its own encoder was more than ten times faster than RubyAMF.

Despite these dramatic improvements in performance, the team still found that encoding in some cases was too slow. On careful examination, it turned out that objects with many fields could simply not be encoded very quickly. The team consequently changed tack, creating its own custom string format which it then wrapped in an AMF message and sent to the frontend. This resulted in considerably better performance on objects with many fields. However, the team realised that it would be even better if a common string format was used since then it could take advantage of open-source libraries to parse data very quickly. JSON (Javascript Object Notation) was the obvious choice by this time. This again resulted in improved performance. But on reflection the team realised that wrapping JSON strings in AMF messages was actually redundant. JSON strings could simply be sent as responses to frontend requests via a RESTful API (Representational State Transfer). The added advantage of this approach, the team realised, was that such an API could interact with any kind of web client, not just an Adobe frontend, meaning, for instance, that the team could create a mobile app that could fetch data from the server via this API. The team consequently rewrote the APIs and on testing found that speed was twenty to thirty times better than at the beginning when the team was reliant on RubyAMF.

A similar weakness of out-of-the-box solutions confronted the team when it wanted to check the server regularly for changes to projects. The team initially tried to harness the built-in technology of Flex to run requests every few seconds to check for changes to projects. This immediately ran into performance issues. Responses to requests were often slow owing to database reads or because of background tasks running on the server at the same time. It was obvious to the team that this would only worsen as projects and the user base grew. Given the volume of requests expected, requests needed to be handled extremely quickly and not place demands on the server or the database.

On reflection, it occurred to the team that the nginx web server was able to serve small text files extremely quickly. What this meant was that all the team needed to do was store a timestamp of the last change to a project object in a publicly exposed text file in order to allow the frontend to check for changes to projects very quickly. Many web clients could request this text file every few seconds and the effect on server performance would be minimal. The team only had to ensure that this timestamp was updated quickly in response to changes. The web client could then poll the server every few seconds, check the timestamp and if it had changed update the frontend to reflect any changes. This in turn compelled the team to build a dependency framework for the frontend so that, for any change in the timestamp of a project, dependencies among objects could be resolved and changes propagated and reflected in the interface.

This left only an issue with data transfer. At the beginning in response to requests from the frontend, the server had been sending entire projects with all their files and comments in response. For large projects, with many files, companies and folders this would inevitably lead to performance issues. To tackle this issue, the team decided to partition projects into two types of folder, ‘dropbox folders’ and ‘vault folders’. Under this arrangement, when the client requested the root project object (which could encompass thousands of objects) the server would only return the folder structure. The client could then request in turn each of these folders. The outcome of this partition was that any one request would at most return a few hundred objects, even if the relevant project had many companies and folders. This would not cause any major performance issues.

By the end of the work, the team had a working tool that would make collaboration between architects on construction projects easier and much less prone to error. The team knows of no comparable tool specifically for architects available on the market.

Some comments on the above

It’s worth noting what’s different between this and the technical data collection, what’s not, and what matters or does not matter in the translation.

The first obvious difference is that the technical narrative makes copious use of HMRC jargon, and rephrases things so that they may be understandable by someone who is not familiar with software development (which is the case of the vast majority of HMRC inspectors).

So – the above is how to write a kick-ass narrative, but does my project qualify, I hear you ask? Come this way to find out …

Categories

TWITTER

 
GrantTree  @GrantTree,Nov 28
Puzzled about the R&D Tax Credits and Grants relationship? Need insight about how to successfully access both? https://t.co/JVDoxT6zam 
GrantTree  @GrantTree,Nov 24
We unpick what yesterday's Autumn Statement means for the future of R&D in Britain and how it impacts your business. https://t.co/2XP90BmL4Q 
GrantTree  @GrantTree,Nov 23
RT @Payah:good news for @GrantTree friends and clients! https://t.co/8lAbYYUcaG 
GrantTree  @GrantTree,Nov 07
The age old question (well in R&D Tax Credits anyway!): should you file with your accountant or a specialist? https://t.co/HEChpmvvNM 
GrantTree  @GrantTree,Nov 03
RT @BizAdvice_UK:Find out which tax credits and reliefs you are eligible for as an #entrepreneur. https://t.co/Z141n2icPq https://t.co/zkO6TS2W5Q