How did I start writing specifications and accidentally develop a new method?

Or why I didn’t settle for the known and proven methods

This article is the behind story of the functional specification writing method called WikiSpec you can read here. This story has been told in Hungarian some years ago and because of its popularity I thought I would present it in English.

For a long time, I have been writing documentations. I’ve started with business requirements documentations and later changed to writing a more complex functional specifications.

A brief or business requirement can identify the basic requirements of a project so that we can get on the same page with the project participants at the early stages of the project. New ideas, concepts, and details constantly revised in this document. Ideally, the entire project team should be involved in editing it.

As the projects and the details are planned, the document grows. After a while these requirements become a much more detailed description, more specific documentation for the project.

Often these lengthy documents contain so much information that several logical stumbling blocks are created. Let say if one principle of operation changes, it affects the operation and functions of other parts in the documentation. It’s more complex if the elements and functions are repeated many times in the document. Keeping these modules in mind is difficult, especially when several people are editing or just working on several projects in parallel.

I have written many specifications: 40+ specs that have been deployed and more than 20 docs for projects that were abandoned or not implemented. Not counting the table of contents, just the necessary content, there are both shorter (5 pages (A4)) and longer (93 pages) versions. For each project, I have slightly improved my specification method until I found a proven structure and a suitable tool.

Yes, there are different standards, such as System Requirement Specification (SRS). In my experience, almost nobody except a few hardcore developers liked to read it because it is too arid and very often not properly structured.

THE BEGINNINGS AND THE FIRST SLAP

The year was 2011, I had been working in the world of digital marketing projects for two years at a multinational marketing agency. Usually I used to get briefs that described the client’s needs for a web portal or for digital creatives. Think it like a brief messages: “We want a [digital solution name] for our campaign. Here are the brand design guidelines.” and that’s it. Basically our team had to think about everything and most of the solutions were accepted easily — even if they were poor at UX.

One day I came across a “more serious” briefing for a web portal I was working on. I received an e-mail with a Word doc that was thought through. There was a detailed target group definition, a sitemap, wrote what elements and content they would like to have on each page, so it seemed detailed to me. Our team had to design the UI and develop it. It essentially left me with the management tasks: the appearance of it meant I almost didn’t have to think about whether the concept and the context were even right.

And this is where I got my first big slap with a large trout right in my face.

So, the client had thought through the interfaces superficially, full of inconsistencies and gaps. Even though the user interface was beautifully designed on this basis, the eventual result was a portal that was neither user-friendly, nor logical. This led to us a lot of change requests (CR) and feature requests (FR). This isn’t even a problem in an agile environment, but the budget is not flexible, the number of man-hours is spiralling upwards and the end of the tunnel is constantly receding. In the end, the project was not even a zero-sum failure, but a huge one.

The problem was that the functions were not well defined in the document: the recurring elements (e.g. a user data) worked under different conditions in different parts of the documentation, and there were no scenarios for error or edge cases. Therefore, there were different interpretations of what was written, depending on how many people read the complete document.

The client wanted more; the developer wanted less; the designer wanted something beautiful; while I, the PM, just envisaged a happy project completion as soon as possible, as I had other projects to look forward to.

Unfortunately, one of the enormous problems in this industry is once the project is over, there may be maintenance tasks with the “finished” product, but no substantial further development is possible. Everybody was happy that we got the minimum needed out of the project. Someone may call this as MVP (Minimum Viable Product) but the thing that there was no later improvements, but a finished product.

The finished portal was used by users, but apparently because of the need and the content, not because they liked it.

After the incident, I took a deep breath and started working on incoming projects with the new experience.

THE “RECOVERY”

Other clients continued to send one or two paged briefs. No problem: we are the experts to work out the details. The business requirement documents still was a rarity in the world of marketers at this time.

Based on the briefs I received, I wrote the business requirements. I, the PM, planned the structure of the website, included operational plans that I thought might be important and also tried to be as precise as possible about how they would work, leaving little chance for ambiguity. Keep in mind UX wasn’t a popular role in the early 2010’s years. It was like a contract, where the goal is to find what the other party doesn’t think about the project.

I sent the document, which I thought was ready, to the clients, who read it and commented on it. Based on the responses I received, I changed the content — it went on until we found common ground. If they were lazy to read it, we had a document to refer to, so we avoided the free CRs. It was a win-win for us, even if it took a lot of time in the early planning stages.

Once we had the docs completed, we could get on with the design. Most times, while the specification was being built, the visual design was already going on in the background so that there were no delays. We’ve already aware of this process was not very efficient, as we would have to change the designs later.

Once the design was done, it went to development, who saw the design and read the document together and put together a workable result. For the first time even the project was complex, there was much less CRs. We only had to concentrate on bug fixes. It was completely “waterfall project management” with the minimum presence of agility.

However, I didn’t count on follow-up at the time: if something changed in the system later, I didn’t implement it or not well. Later, with the development of a new feature, this again led to logical anomalies in the system and the start of a scramble.

Fortunately, such cases were rare, because typically we had to design and develop quick-run promotional microsites or portals for marketing campaigns, event websites, simpler ecommerce-like sites or creative technology solutions for events (mostly widgets). These projects would soon end and subsequent development would be redundant unless they were pulled out of the hat again later for another campaign.

As I evolved, I got more digitally savvy clients who commented smartly on documents. So I had to keep expanding the functional specifications. I did a fair job on documentations but still not enough.

THE PARADIGM SHIFT & THE BIRTH OF THE “WIKISPECI”

In 2013 I changed jobs to a Tech Project Manager at one of the biggest multinational digital marketing agency’s development team in my country. It was a different league: more professional development work and I also got two major international clients at once: one of them asked for a systematic enhancement of a custom CRM with 200 000 active users running for several years, while the other one wanted trendy and youthful solutions for events.

Deepwater. Marianna Trench. I had three trial months to prove it.

The challenge wasn’t even creative technology, but CRM. My predecessor had written specifications that brought tears to my eyes when I opened the Word files. These tears did not come from happiness — an untold amount of descriptions of functions and interfaces, sprinkled with a business logics. It was closer to an SRS documents and thus to all the dry documentation I had been avoiding.

The first thing I did after the shock was to swim up, take a deep breath and then dive back into the deep end: rethink what I could use from what I had learned so far and what I could do with the experience I had now.

I knew I had to put in a lot more energy than I had before, but I also knew I couldn’t keep so much information in mind, so I had to resort to tricks.

I continued to start the doxing process by thinking through the site map, formulating the options that could be found on them and marking who had access to each.

And here the big change came…

…I left my previous job having to draft and send out many contractual and policy documents to lawyers for approval. In these documents, there were a lot of references points within the document, so if the content was supplemented, it was sometimes necessary to refer to another page (“see page 8”) or numbered element (“see 1.3”).

I already knew that the cross-referencing function in Microsoft Word was a great way to dynamically refer to other numbered points. If the numbering changes, it’s handled in the referenced text. This also came in handy in spec writing, because it allowed me to mark recurring items in separate sections. Not just functions, but elements or concepts too.

E.g. when designing a blog or portal, the element name “article title” or “lead text” is used in several interfaces, but I only specify it in the description of one of the interfaces.

I cross-referenced back to this section describing the other interfaces. I realized that this was a poor decision because the more items I can reference, the more I have to remember where I used it first. The solution is to organise everything I want to refer to in separate chapters.

The specification was already made up of three parts:

1. Brief (concept description for whom, why and what) and development environment (e.g. server, OS…etc.)
2. Site map and site structure presentation
3. Dictionary explaining the attribute of a particular element (e.g. what is the “article title”)

So, if I want to display something in an interface, I have to look it up in the dictionary part: if it’s not in the dictionary, I create it as a separate item and create a short description for it. But it also works backwards: if I start filling in the dictionary and get stuck, I can continue describing the interface.

I have used this solution for months and in a few projects. I was immensely proud that with relatively minimal memory-work I can easily see through the complete system. And the icing on the cake is that the planning part is about feeding itself because of the methodology.

It’s important to note that I have involved the developer colleagues in the design process as well, who have honestly read through the documents and roughly challenged it where they could, looking for logical pitfalls or just indicating development difficulties. It was a particular pleasure to receive suggestions for a more efficient solutions I didn’t think of.

It was very productive, and in addition, the client was honest in reading the documents, commenting on them and checking with their staff and lawyers whether a solution would fit into their business processes.

I started experimenting with having the specification describe a complete user process, a user story, and referencing the elements of the sitemap and dictionary. However, it was not a very efficient solution: it was very focused on the user journey of a single persona, but it was much easier to imagine the fulfilment of a more important goal of a single user. However, as a supplementary chapter, this could be great information.

And that’s when it occurred to me that there should be a chapter for features/functions too. The reason we need this is that there are many functional principles that work in the same or very similar ways across interfaces.

Let’s clear why this chapter is so important. Take a simple function: requesting a new / forgotten password. The request can be done by the system sending a new password by email or by sending a link with a token to a password change page. These are two different mechanisms, they can be invoked from multiple interfaces, but it is unfortunate if the functionality works differently on these interfaces. Therefore, I will describe this function as a subsection of a section in functionality chapter. In addition, this description also includes and even refers to the dictionary terms: sticking with the present example of user email, password, password token descriptions which are all explained in terms of what they are.

Simple and great.

THE TRIED AND TESTED RECIPE

It’s 2014, after many projects, I’m still editing documents in Word with cross-referencing, tweaking my method.

My spec writing habits consists of the following points:

1. Brief (for whom, why and what concept) and development environment (e.g. server, OS…etc.) — this remains as it was
2. Functions: presents a functional logic in an experiential or objective way, building on the concepts and covering specific cases.
3. Interfaces (Pages and Modules): these describe the structure of a page or module, referencing the concepts.
4. Terms: these describe the meaning of a participant or element and show their limitations (later they also indicate data types and possible error messages)
5. User story: a collection of user flow examples, building on the elements of the specs.

I cover each chapter in more details in the WikiSpec article.

Last but not least, each section will find the information relevant to it:

• Terms = Backend developers (for database) and Frontend devs for frontend validations rules (eg. on forms)
• Functions = Stakeholders, Backend dev, or business logic can be made from this
• Interfaces = Stakeholders, Designers and Sitebuilders

Remember, I wrote earlier that my predecessor also designed business logic for developers? Business logic describes how the elements of an application communicate with each other in (semi) developer language. The specification contains the same business logic but in human language. The customer can nod to it, because he understands it.

The functional specification can be as technical as you like, but since its purpose is to let both the customer, designer and the developer know what the result should be, it is worth keeping it simple.

NOWADAYS

It’s 2021, I’ve changed my almost 9 years old project management hat to a UX Designer about 3 years ago and still writing functional specification with the same concepts, mentioned above, mostly in Notion. This helps me design the wireframes for complex sites, helps prevent logical errors and I can easily approve the behind logic of the visual plan even if i design wireframes and cding them to a complex & dynamic prototype with conditional logic.

Don’t forget it’s very important to revise this documentation with your team together once new information has landed to the team, so everyone will read the actual information in the documentation.

If you are interest in more details in the WikiSpec, you can read my related post.

Thank you for reading my story.