WikiSpec — A How-to-guide to write a better Functional Specification
How easy and enjoyable specification writing can be with the WikiSpec framework.
Table of contents:
- What is WikiSpec
- Understanding the concept of WikiSpec
- WikiSpec structure and chapters
- Advantages of WikiSpec structure
- Prioritization- & status-marking techniques
- Cue, tips, tools
For easier understanding, I made a basic WikiSpec example in Notion, which you can reach here:
https://www.notion.so/wikispecsample/WikiSpec-Sample-Documentation-8a8fd91a030b40389c711a0d827885a2
1. WHAT IS WIKISPEC?
The WikiSpec is a specification writing method developed for years of writing specification documents.
The main idea was to create a wiki-based thesaurus alike documentation to create a functional specification that includes dynamic cross-references to each part of the document. The method has been revised many times over the years and used to document complex systems in a well understandable framework to deliver to all project members or product teams.
WikiSpec can easily integrate into the lean, agile, or hybrid project management methodologies because of its modularity and consistency. You can use it in either continuous or intermittent product lifecycles too.
About WikiSpec, I first wrote about exactly 2 years ago in Hungarian, so it’s time to talk about it in English. 😅
2. UNDERSTANDING THE CONCEPT OF WIKISPEC
Consistent terminology and dynamic referencing, citation
Reading documentation is a hard stuff because the reader must read all the documentation and remember the definitions. Many times won’t read the entire specification but a part of it, so may miss some essential terms and seek it in the doc.
The documentation writer often describes the same participant with properties or attitudes in an entry that can be found in another section, missing some critical information. The reader will be confused about the final decision, or worse, won’t know if they read the correct behavior. For example: on a “Register page” (Interface), the “User password” (Term) may 4 characters long at least, but on “Login page” (Interface) the minimum length is 6 characters. Same entry in the database but different limitations on each page, but what’s the correct information?
The essences of WikiSpec is
clarity, organized structure and easy changeableness of the crossed-reference terms
so declare a name for an item and revise it later.
To do this, we first need to create 3 main chapters in the specification: Functions, Interface, and Terms. Let’s call them FIT. More on these chapters later.
Each chapter contains entry-words or articles which include a detailed description of a term, like a layout description, term definition, or function introduction. Each description may contain a text that refers to another chapter’s entry.
You can refer in two way:
- With static referencing, you create reference which won’t update automatically. So when a referenced article’s title/name changes, you have to update manually in the referencing entries too. The documentation may be inconsistent if you forget to update the entries.
- While the dynamic cross-reference is a linked and auto-update reference to other parts of the document, each time the referenced entry’s name changes, it will update in all parts of the document. It’s done automatically, it will be consistent all the time, and you don’t have to revise it manually each time.
Let’s see an example of why it’s important to update the references:
By using static referencing, within the Interface chapter, we create a “Login page”. We have to refer to this entry when describing the “Login function” and the “Forgot password function” in the Function chapter. Later we figured out that the interface is not a page but a modal, and we rename it to “Login modal”. Now, everywhere where the “Login page” is mentioned should be updated manually — so in the “Login function” and in the “Forgot password function” too.
We can use the editor’s Search & Replace feature to rename the term by overriding the word “Login page” to “Login modal”.
But it isn't the ideal way to revise the content because:
- we may accidentally update words we don’t intend to, or
- we missed the words that contain typos (“Lgoin page”) or
- maybe we called it something else like “Login interface” in some part of the documentation.
The ideal way to use a word editor that supports the dynamic cross-referencing function to build up sentences from referenced terms. Softwares like Microsoft Word or Notion App will be your partner because they have dynamic cross-reference function.
Modularity
If an entry can be broken into smaller chunks, just separate into smaller pieces and cross-reference them. Also, you can group them (e.g., Full name = First name + Last name), and you can refer to the group itself (Full name) or just the part of the group (First name).
Storytelling
When you describe a term or definition, try to use storytelling techniques mixed with modularity and referencing other parts of the document.
3. WIKISPEC’S STRUCTURE AND CHAPTERS
The WikiSpec must be built from chapters, sub-chapters, and their word-entries or articles because of consistency and modularity.
WikiSpec has 1+3 main chapters:
- Brief, Goals, Scopes, User journey (or Epics)
- Function (or Features, or User Stories)
- Interface
- Terminology
We will work mostly with the last 3 chapters because they contain elements that can reference each other. So you can describe user stories (in Function), layout description (in Interface), and explanations of participants, roles, database elements, and attitudes (in Terms). I will relate them as FIT.
As I mentioned previously, each FIT chapter builds up from word-entries (or articles) that describe a layout, a function, or a database term’s definition in detail. And these entries will contain referenced text to each other.
So let’s look at each chapter. Please notice that each chapter description ends with a link to the actual Notion app example.
Chapter #1: Brief, Goals, Epics, Scopes, User Journey Map
The first chapter is an optional part of the WikiSpec, but I recommend using it.
This chapter briefly describes who and why the project is done, the product vision, the project scope and explains its development.
It also describes what the organization, business, customer, and/or project intends to do with the specified product and the users' presumed or best case paths in the system. In other words, this is a strategic explanation and summarizes the user’s purpose with one or more functions and how it affects the system or the business.
This chapter may be called Goals & Epics in the SCRUM project management framework, which includes summarized user stories, while UX designers can describe here Goals & User Journies.
In the example below, the text in “(classic bracket)” helps to understand the context - you don’t have to write in the specification. The words in [square brackets] point to a specific element in one of the FIT chapters mentioned above.
The [user] (Term) completes the [user login] (Function) on the [login modal] (Interface) to access additional [registration-related features] (group of Function). The goal of our [owners] (Term) organization is to have [10% sign-ups] (Goal) on a given day, which can be tracked in the [Reports] (Interface) admin section in the [Daily Sign-In Rate] (Interface) section. If the numbers are succeeded, [personalized ad impressions] (Term) will cover 2% of the company’s revenue per day. If the numbers are under the expected key value, the [product manager] (Term) will check the [bug log] (Interface) to see if any of them have caused it.
In the example above, you can find information such as:
- Which person is responsible for the project/product/tasks (e.g. “owner”, “product manager”, “stakeholders”);
- How this helps to reach the company’s business goals (e.g., “personalized ad revenue”) — this info is an excellent help in project planning to prioritize tasks;
- What’s the goal completion rate or the KPI (e.g., “10% daily successful login”)
As you can see, this chapter is useful mainly for stakeholders, so the managers and the decision-makers.
Example: https://www.notion.so/wikispecsample/Brief-Goals-Epics-User-Journey-1b984c8e215d4738abb8b9b6b4278f31
Chapter #2: TERMS
This chapter describes various terms (participants, roles, elements), and database elements with its attitude description must be a reference in other chapters. Essentially it’s the specification’s vocabulary.
Typically, the developers will find this chapter helpful because they can use it to build up the database, set the database entries properties, and set backend and frontend validations according to the information written here.
Because of the modularity, the term has multiple parts:
- Name of the term (e.g., “Registered user”) — you will refer to this information, so if you rename it, it will be revised every part in the referencing parts.
- Definition of the term (e.g., “This user type has access to the [registration-related] functions”) — Mind that here you can refer to other entries/articles too. In this example, I refer to a function entry group (registration related) but may reference just to a function entry.
- Entries’ properties (e.g., “character limits”, “example data”, “note”, “error messages for input field” … etc.) — Here, you have to collect every useful information that relates to the entry.
- Term’s types (e.g., User types like “Visitor”, “Registered User”, “Admin user”… etc.) — to break down terms to roles or by behavior
- Term’s statuses (e.g., “Inactive”, “Active”…etc.) — to see how the term works in each condition.
The corresponded term entries can stand as individual entries too, but grouping these terms to a higher level term provides easier transparency. For example, you may collect the user-related sublevel information (e.g., “User first name”, “User e-mail address”, “User password”… etc.) under the term “User” which also includes the types and statuses.
Other grouping technique to (re)group already broken down terms. For example, in many cases, the last name and first name are listed together, so if we refer to the user’s full name somewhere, it already includes the first name and last name with the properties, limitations, and data-notes.
According to dynamic-reference, you can use cross-reference links anywhere to jump other entries. Still, it’s not necessary to refer the term entries to interface entries manually (e.g., User email (Term) is in use on Login page (Interface) and Register page (Interface)). Maintaining the terms on which layouts are used takes too much time and hard to keep in mind. So far, I didn’t find any app or plugin that automatically-collects the list of the referencing entries correctly to the actual term.
Terms chapter example:
https://www.notion.so/wikispecsample/Terms-4-33f8c8cb1b26443ea731f5470d689b1e
Chapter #3: INTERFACES
The second part of the FIT describes the structure of a page, interface, sections, or modules within a page.
This chapter is useful mainly for designers and front-end developers.
It has two mandatory parts:
- Interface name (e.g., “Login modal”) — you will refer to this name.
- Description (e.g., The [user] can [log in] on this interface”) — Who and what can do on this interface.
- Content incl. the related Term entries (from Chapter #2), their type (e.g., input fields, buttons, texts) or call-to-action function or link to an interface (e.g. “by clicking a button it calls a specified service/function and navigate to another page”)
Here is a simple example of an interface description:
Login modal
The [user] (Term) can [log in] (Function) on this interface or click on the forgot password button to initiate the [password reminder] (Function) on the [password reminder part] (Interface). By clicking on the register button, the [user] (Terminology) gets to the [registration page] (Interface).
Also, it may include some additional parts, like
- Related designs (e.g., pictures or links to the layout design)
- Related articles from Function chapter
- SEO data
- Possible restrictions (e.g., what each user roles do see this interface)
If a page has recurring element groups (like login module), it is worth explaining them in a separate entry and refers to it on other interface entries.
Interfaces chapter example:
https://www.notion.so/wikispecsample/Interfaces-7-63ae0a9d97dd427e9c02a6a3229538e9
Chapter #4: FUNCTIONS, FEATURES, USER STORIES
This chapter is the most crucial part of the FIT: the functions (or features, or user stories) focus on a detailed explanation of a given case and demonstrates the logic of operation. It can be described either experientially or objectively; the point is to be detailed.
Stakeholders and backend developers will love this chapter because it contains deepen details of the goals, epics, and user journeys mentioned in chapter #1.
An example of the description of a Function:
Login function
The [user] (Term) can log in on the [Login modal] (Interface) its account to [edit the profile data] (Function). To proceed the successful login, one has to give the correct [user e-mail] (Term) and [user password] (Term) pair. The login fails if the given data doesn’t meet with the data in the system.
Also, you may add the following details as well:
- Related participants (term entries) in list format (as dynamic-reference)
- Related interface entries in list format (as dynamic-reference), but as I said in the Terms chapter: only refer to the Interface entries if you would update it regularly (or auto-generated), or it may be confusing if there are missing parts.
- Related function entries in list format (as dynamic-reference)
- Possible successful and unsuccessful causes and solutions. Here you can determine which other function is associated with (e.g., data validation by clicking a button) or what message will appear in a particular case.
In my experience, if something does not fit into 2000 characters, it is probably an epic’s description (mentioned in chapter #1), so you may break it down to smaller functions, user stories.
Many times I aggregate the functions entries to referable groups (e.g., “user functions”, “admin functions” and “system functions”…etc.) so I can easily refer to a group of functions as I do with the User’s full name in the Terms chapter.
Functions chapter example:
https://www.notion.so/wikispecsample/Interfaces-7-63ae0a9d97dd427e9c02a6a3229538e9
4. ADVANTAGES OF WIKISPECI STRUCTURE
Because WikiSpec is modular (built on chapters), it is an excellent advantage if you get stuck in writing a chapter (like an interface term), you can navigate to another one (e.g., a function) and continue the documenting by adding a new feature which has an impact on the Interfaces and Terms chapters.
Some people like to write functions and features, but some like to summarize interfaces or think in User Stories. These chapters also contain terms: if you do not have a term in your Terminology chapter, you can create it right away and explain its limitations.
For example, you write the information architecture of the login interface in the Interfaces chapter. Still, if you do not have the term “user password” you cannot refer to it, so you have to create the entry in the Terms chapter and define it. This typically gives the idea to create other term entry or part of the term associated with a user. If not, you may continue writing the Interfaces chapter or create a new function entry used in an interface entry.
As I mentioned, by maintenance the FIT chapters
the specification generates itself while you write it
because it’s easy to recognize the missing parts or logical errors.
5. Prioritization- & status marking techniques
Labeling prioritization
Because prioritizations aid product and project management, we can use the labels according to the MoSCoW prioritization technology in the Functions chapter.
We can label each element’s title with emojis (e.g., circles) or color the title if the editor supports it. Prioritization comes essential when the prioritized terms are in a chapter listing view OR appear in the referencing text. The reader can focus on the most important entries that are probably in connection with each other.
Here is an example of priorities:
- 🔴 Mandatory (or High)
- 🔵 Required (or Medium)
- ⚪ Good-if-Yes (or Low)
- ⚫ Not necessary
If you are working in an agile environment, you can also sort these user stories into a User Story Mapping matrix board. This table shows the user’s general “progress” directions/paths and options, organized into larger groups (e.g., Login related functions, Search related functions). And you are in luck, if you use the Notion App, you have the option to create inline tables that allows you to collect entries in cards and organize them into each step of the table, and even group them according to Releases states.
Labeling progress statuses
You can label the term’s title what the specific status is, so the readers and other editors will see which part of the specification is in progress or needs to add feedback.
You can use emojis, but be sure not to use the same as in the prioritization part.
Here is an example of signs of progress:
- Not started: 🏴 or ⏹️
- In progress: 🏳️ or 🚧
- Finished: 🏁 or ✔️
- Marked for verifying: 🎌
- Marked for deletion: 🗑️ or ❌
As you can see, I’m using marks for finished parts too, because many times, terms without markings are abandoned entries of the specification and need more attention.
You can also put the entries on a Kanban board to see the progression in a matrix view to be easily manageable.
6. Tips, tools, cue
For editing, I recommend using Notion App, a modern text editor using blocks with a drag and drop feature, and have a speedy and intuitive referencing feature necessary to create a WikiSpec. You can open pages side-by-side, and you can easily navigate back using the browser’s back button or by the breadcrumb. Other features like Kanban and other board styles, easy content embedding, two columns layout, coloring, and styling is making one of the most effective editors on the internet.
There are other modern text editors in the wild (Coda, Slab, Quip), but they are not as powerful as Notion in my experience.
I’ve started writing business requirement documents more than a decade ago with a more popular alternative: Microsoft Word. Here you can use the built-in cross-reference feature, which is not so comfy and a bit basic but works well. If you are ready to invest in MS Word Add-ons DocTool’s Cross-reference plugin is a good extension to use cross-referencing effectively. I used this plugin for almost two years before switching to Notion in 2018.
Also, you can use Wikipedia alike editors like MediaWiki or other document writing tools like Confluence.
I hope you are now ready to write the specifications more easily and apply your ideas effectively in the future. Please notice: Wikispeci is not omnipotent; it takes a lot of habits to think, but by the end of the day, it just works because managing term, function, and interface relationships are very simplified.
- Thanks for your time and happy spec writing! -
If you wanna talk about the article or any UX & tech-related topics, feel free to contact me: https://www.linkedin.com/in/abramovgabor/
