Hello, my name is Yamashita from the Development Department.
I joined the company in May this year, and this is my first time writing a blog. I look forward to working with you.
At Tatsuno Information Systems, I am in charge of Project Manager (PM), and in my daily work, I mainly create documents.
So in this article, I'd like to introduce how to write documentation that is easy to read and understand for customers and developers.
Click here for table of contents
- 1. About requirement definition and specification
- 2. What is an easy-to-understand document?
- 3. how to simplify the documentation
- 4. structure of documents with figures and tables
About requirement definitions and specifications
In general, a requirements definition document is a document that a vendor creates based on an RFP (request for proposal) from a customer, saying, "We will create this kind of system.
On the other hand, a specification document is created internally by the vendor as a pre-coding document (more precisely, it is called a detailed design document).
We do not do waterfall type development.
There are also many times when requests are raised from within the company.
Perhaps because of this, it is treated as "requirements definition document ≒ specification document", and programmers code based on the document created by PM.
Therefore, I think that the documents that our PMs create are quite system-oriented.
What is an easy-to-understand document?
That's about it for the preamble, but I'd like to get to the point.
An easy to understand document is a"Simple.. It comes down to this.
Humans process a lot of miscellaneous information in a limited amount of time. TheEliminate miscellaneous information as much as possible and make it simple and clear.The result is a document that is easy to read.
Of course, it is also important that the text is correct. It is very difficult to read if the subject is missing, if the "te ni o ha" is absurd, or if there is any misrepresentation. But that's not so important. This is a little off topic, but actually, I once attended an editing and writing course in order to improve my writing skills. However, they didn't correct my writing and mainly taught me how to conduct interviews and how to include specific numbers. While we're on the subject of sidetracks, I'd like to give you some publicity.learningBOXin order toreport functionand can be used by students to submit their writing and the teacher to correct it and give feedback. It's really just an advertisement. I've achieved my quota. Now that I've achieved my quota (?), I'll get back to the main topic.
How to simplify your documentation
This is easy. It's not a sentence.Pushing charts to the forefrontThis makes the documentation much simpler.
I'm sorry to tell you this story again, but it was at a company I used to work for. I was supposed to explain a document to a customer. I started to explain the document with great enthusiasm, but there was no sign that the customer was reading the document. When I observed carefully, I realized that the customer was not reading the text, but was looking at the flowchart all the time while listening to me. I see, even if I put it in my own words, a visual diagram gets into my head more smoothly than text. Since then, I've always included charts and diagrams in the beginning of every document I create.
Organization of documents with figures and tables
Finally, I'll explain exactly how the document is structured, with the figures and tables coming early in the process.
Our company had 2 PMs including me until May and then we are increasing the number of PMs. Therefore, documents will be standardized and templates will be created. Until then, I will create documents in my own style. The following structure is my personal style.
1. System overview (a few simple lines of text)
Overall diagram of the system (flowchart or screen transition diagram combined with ER diagram)
3. table definition document
4. Details for each screen
It's roughly like this.Gradually go from a visual overview to a detailed descriptionI try to do this. I think this will improve the reader's understanding. However, this is just my personal case. How it will be standardized in the future has not yet been decided. Of course, I don't think this is the right answer. I would like to continue to work on creating documents through trial and error so that both customers and developers can understand the system smoothly.
English 
Japanese