Cover
Michael DubakovFounder, Fibery.io
Guides

How to write beautiful Feature Specs in Fibery

February 11, 20214 min read

Here is the article I wrote about Visual specifications. Still relevant!

Features specifications are not easy. They are especially hard when your tool impedes your thoughts. Surprisingly, specialized product management software makes it so. Productboard, Aha! and most other tools just don’t support good docs.

This is Aha! I don't feel like I can write a good functional specification here...
This is Aha! I don't feel like I can write a good functional specification here...

As a result, product managers write specifications somewhere else: Google Docs, Confluence, Notion, etc. The problem here is that a spec is separated from a feature itself. It just makes everything more complex: all people have to have access to the wiki, you have to put links from features to specs, you have to discuss specs somewhere (but there are two places, where it should be done?).

The solution is obvious:

Feature spec should be inside Feature

You should use a single tool for Feature management and Feature specification. For example, in Fibery every Feature has a collaborative area where you can write text, add images, link User Stories or Tasks, discuss things and quickly break down work.

Basically, this is a wiki page inside every Feature!

Feature in Fibery has spec inside
Feature in Fibery has spec inside

Insert diagrams and images

Images and diagrams help to understand what is all about, and understanding is your top priority as a spec creator. Understanding creates shared context, leads to faster solutions and fewer errors in product development.

In Fibery you can add images and create diagrams quickly. Take a look at this spec with some embedded diagrams and images. Note that you can change a diagram right here, without switching the context and leaving the tool.

Use images and diagrams to make specs easy to understand

Use images and diagrams to make specs easy to understand

🦐 It’s even better to see the whole diagram in the spec without the extra click, but Fibery is not there yet.

Collaborate & discuss

Some tools don’t support collaborative editing. It leads to huge problems for serious remote product teams or even colocated large product teams. You are never sure some Feature is in the editing mode by another person. Collaborative editing is an absolute must-have thing for the spec creation process.

Specs are not set in stone. There are some unclear points and some controversial things that demand clarification and discussion. Some tools just have a single comments thread for a Feature, but in reality you want to refer a very specific place in the spec, so inline comments are much better here:

Use inline comments to discuss specific place in a spec

Use inline comments to discuss specific place in a spec

Link other relevant entities (Features, Ideas, Insights)

It’s handy when you can quickly add a reference to another relevant entity, like to some Idea or other Feature. It can add some perspective to the spec and form a wider context for a spec reader. It is especially important in a product vision document, but in a functional specification it’s still relevant. Sure, you can add links in any tool, but if it’s just an URL, you have to switch context, find this thing, copy the URL and add the link. It’s much faster to just type some keywords and find relevant entity:

Quickly link a relevant entity into a spec, quickly see its details

Quickly link a relevant entity into a spec, quickly see its details

Create work items fast

When Feature specification is ready, the next step is usually to break it down into User Stories or Tasks. You can create them one by one, but the better process is to brainstorm the list of User Stories with the product team, write it as a text, and then magically convert this text list into a real User Stories list:

Create User Stories or Tasks from a Feature. Fast.

Create User Stories or Tasks from a Feature. Fast.

Specs importance are often underestimated. In Fibery we try to make this experience enjoyable and effective. If you are a product manager or a product owner, I bet you will like it.