How to write an interactive description document that everyone agrees on?

Recently, a design partner asked me what kind of interaction description is the best and what everyone likes. When he submitted the interaction description document he wrote to the members of the requirements review meeting for review, everyone suggested that he write it more reasonably, which gave him a headache.

[[419542]]

I told him:

First, different job objects: There is no perfect interaction description that can impress and amaze everyone. After all, since different people read the interaction description document, they will have different requirements for the interaction description document, which is the result of job attributes. For example, front-end developers want detailed fields, initial default values, data retrieval interfaces, etc., while leaders only need to see the large interaction links that ensure there are no errors in the business direction.

Second, different perceptions of the same position: the perceptions, work experience, personal preferences, personality and temperament of different members of the same position will also make it impossible to have an interaction description document that is perfectly suitable for everyone. For example, a front-end engineer who has been deeply involved in an industry for many years can deduce other aspects from your existing text even if your interaction description document is not so detailed, and can also help you to supplement and improve it; for a front-end engineer who has just entered the industry, if you don’t write it in detail, he will go crazy, and when the project time is urgent, he will make up the interaction details by himself. Later, you will also go crazy when you check, but it’s useless, because you didn’t write the interaction details clearly and missed them.

Third, different use occasions: Different interaction documents are required for different occasions. For example, when communicating with the other party face to face, the interaction document can be written less; but when communicating with the other party through online tools, it needs to be written as detailed as possible; if it is a meeting-type review, then you need to do enough homework in all aspects. Simply put, it is like preparing a PPT: for the same topic, the same PPT will need to be designed in two versions for external presentations and internal presentations in the company, one for internal and one for external, because the use occasions are different.

Fourth, different product stages: the interaction document describes the interaction of a product, not other things. If the product is in the mature stage, the product's interaction document often has accumulated many common rules and can be reused, so it is not a big problem to write less interaction document now; but if the product is in the exploration stage or growth stage, generally speaking, reusable interaction assets do not exist, so the interaction document needs to be prepared relatively complete.

Some designers say that since it is impossible to satisfy everyone, I will just write it according to my own ideas. This is not okay. After all, part of our main work is to write interactive description documents, which requires a serious, rigorous and professional work attitude to do this part of the work well. Let's take a look at what to pay attention to when writing a friendly interactive description document.

What is Interactive Documentation?

The interaction description document is used to tell the team members involved in product development about the details of page interaction, including the logical jumps between pages, the interaction of modules within a page, the status of page functions, etc. The more detailed the interaction description document is, the more conducive it is to the correct execution of all parties involved in product development.

Interaction documentation needs to be improved

I have compiled some forms of interactive documentation that need to be improved in my daily work to see what problems exist.

1. The text is dense and has no structure

Almost all designers who have just entered the workplace, when writing interactive documents, are afraid that if they do not write enough, others will think they are unprofessional, or they are afraid that if they do not write enough, they will not be able to express the details of the page. As a result, the interactive documents are densely packed with text, which makes it almost impossible for readers to read and find no visual foothold.

2. The description is simple and incomplete

Designers with several years of work experience are familiar with many common interaction rules, so they are more relaxed when writing interaction description documents. Some interactions are not written in the documents, which leads to the neglect of certain interactions during development.

3. The data is too fake and illogical

The lack of logic in the interactive draft data is a common problem for many designers. One reason may be that the product manager has not sorted out the product logic and details before submitting it to the designer for drawing. Another reason may be that the design time is tight and there is no time to make all the data in the interactive draft logically reasonable.

We have encountered situations where the associated values ​​cannot be associated, the corresponding values ​​of the fields in the table do not match, and the data filled in the form does not match the actual situation.

It is recommended that you present the data as realistically and logically as possible, as time permits or conditions permit, and ask the product manager to assist in completing the data. This will help developers and related readers to understand it efficiently.

4. The image and text are too far away to be found

A few times I noticed that the interaction instructions submitted by the designer would be marked with words like "see Figure X". That is, after reading a description, you still have to go to a corner of the page to find the corresponding picture. This experience is very bad.

One of the principles of interactive design is "stay at home". "Stay at home" means that if you can solve something on the current page, don't go to other pages; if you can complete something nearby, don't go too far away. Frequent switching and jumping will interrupt the user's flow, easily causing the user's thoughts to be interrupted, thinking to be unsmooth, and even possible disgust with the product.

Similarly, the images and texts in our interactive instruction documents should be adjacent to each other as much as possible, so that users can read smoothly and comfortably and understand quickly by looking at the text and the image at a glance.

5. Scattered, a few sentences here and there

The mixed words here and there refer to the text in the interaction description document, which should be described as a whole, but is divided into several parts for explanation. This is a disaster for the person reading the document. He needs to sort out the interaction ideas again and connect the interaction rules together.

When we write interactive documentation ourselves, we try to avoid the above common problems.

What is good interactive documentation?

There are a lot of information about what a good interactive description document is on the Internet. Here I would like to share with you what a good interactive description document is based on my own experience.

First, let’s clarify what is good. Once we have a good standard, we can talk about how to achieve good results.

1. What is good

Usually, the interaction document will be shown to the product manager to review whether the design plan meets the requirements; to the visual designer to guide the presentation of the visual plan; to the front-end and back-end developers to guide the development logic; and to the test engineer to assist in writing test cases. Based on this, a good interaction description document is related to whether the design plan can be implemented to the greatest extent. And if the interaction document is lengthy and the logic is unclear, it will not only be difficult for the reader to read, but also require extra time to communicate with the development engineer. I think a good interaction document needs to have at least the following 7 points:

• Clear value
• Consider all aspects
• Easy to understand
• Clear structure
• Graphics and text
• Only one copy
• Revision History

2. How to do it well

In order to let everyone learn and practice at the same time, I will use the interactive case of "form verification" to explain it to everyone.

Clear value

A good interaction description document is one that can assist project members to complete their work tasks more smoothly through the document, help users solve problems, and achieve product goals. The document is valuable to all parties and is the starting point of a good interaction description document. So, how can we write it to achieve the above results?

On the one hand, the value of this document should be clearly stated, including the background and demand sources of this interaction design, the demand list, the theoretical basis of the interaction design, the value it can bring to users, etc. On the other hand, these contents should be promoted to members to make them feel that the work they are going to do is valuable.

"Form validation" comes on stage:

Consider all aspects

Apart from factors such as the object of document reading, interaction generally needs to consider the following aspects:

a. Overall interaction process

The overall interaction process refers to the interaction logic between product pages.

b. Page module interaction instructions

The page module interaction description refers to the interaction description of the module itself, or the interaction logic between independent modules on the same page, or the interaction logic between modules on different pages. For example, clicking on a navigation tree node will refresh the table content on the right; clicking on a banner will jump to the corresponding product details page and locate the 1/2 position on the page.

c. Page function interaction instructions

Page function interaction description refers to the description of various situations of a single function. For example, input text in the search box and click enter to trigger the corresponding page jump.

d. Display data as realistically as possible

Although it is an interactive description, we also try to simulate real data, otherwise it is easy for readers to make wrong judgments. Not everyone will read the document word for word, so as long as the data is as real as possible, it will help readers understand more effectively.

e. Additional instructions for special circumstances

In many cases, extreme interactions may occur for some reasons, which also require completion.

f. General interaction in one place

It is recommended that the interaction team establish a general interaction instruction library for the product so that they can directly call it up when encountering similar situations.

In fact, when we write interaction instructions, we don’t divide them so finely, and many instructions are expressed together.

"Form validation" comes on stage:

Easy to understand

Easy to understand means that the text, language, pictures, etc. should be easy for the audience to understand and perceive, so as to minimize the loss of information during the transmission process. This is also related to human understanding ability.

Baidu Encyclopedia explains comprehension ability as follows:

• “Comprehension ability refers to a person’s ability to remember things or even knowledge.

There are three levels of understanding:

• The lower level of understanding refers to: Understanding at the perceptual level, which is the ability to recognize and identify an object, and to name the object and know “what” it is;
• Intermediate level understanding is: based on the understanding of the perceptual level, the essence and internal connection of things are revealed, which is mainly manifested in the ability to understand the connotation of concepts, principles and laws, and knowing how it is;
• Advanced level understanding belongs to indirect understanding, which means: on the basis of conceptual understanding, further systematization and concretization, re-establishing or adjusting cognitive structure, achieving coherence of knowledge, and enabling knowledge to be widely transferred, knowing "why" it is. "

When we understand that people have varying levels of comprehension, we should try to simplify professional knowledge at work (we can also simplify it for different groups of people), enhance communication effectiveness, and ultimately achieve the result of completing the team's goals.

Interaction documents should be written in human language, not in professional terms. I remember that an interaction designer mentioned the "invitation" principle when explaining his interaction solution at a meeting. Since the participants were development engineers and product managers, they asked what the "invitation" principle was, and everyone discussed this issue for a long time.

This shows that it is necessary to express things in a simple and understandable way.

Clear structure

In addition to being easy to understand, interactive documentation also needs to have a clear structure.

Clearly structured content not only makes it easy for readers to understand, but also allows readers to understand the author's intentions. To achieve a clear document structure, in addition to complying with some rules, it cannot be divorced from the actual situation of the current document.

"Form verification" comes into play (segment the text and extract the keywords):

Graphics and text

The complementary effect of pictures and text can deepen the reader's understanding of the text and prevent the reader from imagining the corresponding results of the text. Since people's understanding of the same text is not exactly the same, it is recommended that designers try to arrange interactive instructions corresponding to the illustrations.

"Form validation" is on stage (left picture, right text):

Only one copy

Only one copy means that when delivering the interaction description document to the team, do not make multiple copies. Previously, our front-end partner received two interaction documents, one is a pure prototype interaction document, and the other is a visual draft interaction document. The information described in the two is similar. At this time, it is recommended to merge the information of the interaction documents and only submit a complete copy to the front-end partner so that the front-end partner can concentrate on understanding the one copy.

Revision History

It is recommended that the interactive description document retains revision records, which can help understand the change history of the interactive document and facilitate backtracking and finding information. Revision records generally include the person who revised it, the revision time, and the revision content.

Summarize

Due to different project schedules and business complexity, we can't always write the best interaction description document, but we can try to write a relatively readable, understandable and friendly interaction description document. We often say that we are doing user experience, and the interaction description document is one aspect of our interaction ability.

In addition to completing the interaction description document, if you want the developer to truly understand the interaction description, you also need to communicate with the developer in person. Don't think that even if I write it in detail, he still has some deviations in implementation. In fact, as mentioned at the beginning: different people in the same position may have different understandings due to their cognitive understanding, work experience, personal preferences, personality, etc. Especially for some of our very innovative and special interaction points, we need to focus on and explain them to the developer.

In addition, the interactive description document will continue to iterate based on the development of the business. We must continuously optimize our documents with an attitude of listening more, thinking more, and accepting more, and try our best to write a friendly interactive description document.