We write specifications. Part 1. Tools - begin with a simple
So finally we decided to start writing specifications. Since the process itself is new for us, at least let the tools be familiar.
What do we want from the tool? Perhaps all requirements are reduced to one word - convenience. After all, you need to have very good reasons to do something, if it is inconvenient to do it. But we want our colleagues to enjoy writing specifications. Like, for example, from programming.
Personally, I have few requirements:
Option 1. Microsoft Office.
At first glance, a simple solution. We already know how to use Word, it is installed by all programmers, so there should be no problems.
To make it easier to find the right specification, you need to have a centralized storage place for them. Create a project folder on the server with subfolders by the number of projects. We will add our documents here.
Over time, we came up with a design specification template. No, this is not a standard 20-point content that should be in any specification. God forbid. We described the design styles of different semantic parts:
The useful thing turned out to be. Documents have become so fun, colorful, pleasant to read. And you can immediately find the desired part, even without reading the text, only in appearance.
')
Later it became clear that we need cross-references from one document to another. Fortunately, in Word, there is a relatively convenient mechanism for this. You can make links within the document and between documents. Over time, documents began to appear - portals, consisting mainly of links to other documents.
Sometimes (more precisely, quite often) you need to insert into the specification some kind of interface sketch, or, say, a UML diagram. We draw them in Vizio, and then we insert into the specification. The question is where do you store the files themselves? Let's come up with tricky rules - to store related files we will create a folder named like the document, and put additional materials in it.
Results:
Pros:
Lean curriculum curvy ((c) Golubitsky). To start the process does not require any effort other than volitional. All the necessary tools - office software and network drive - as a rule, are already available. All skills of working with documents are retained (if anyone had).
Minuses:
Summary:
The described toolkit is quite sufficient when you are just starting to try your hand at specifying. It can be used in very small projects with about five developers. If you have several projects, several teams, and most importantly, you have already tasted the charms of specifications and you want more, then you need a more advanced tool. For ourselves, we found it in the wiki.
(see Part 2. Wiki - everything is at hand )
What do we want from the tool? Perhaps all requirements are reduced to one word - convenience. After all, you need to have very good reasons to do something, if it is inconvenient to do it. But we want our colleagues to enjoy writing specifications. Like, for example, from programming.
Personally, I have few requirements:
- Convenience search. You need to be able to find the right specification by keywords. Or make sure that there is no such specification.
- Convenience of editing. The simpler the process of writing the specification, the more eagerly our colleagues will do it.
- Convenience of reading. It is known in advance that the circle of readers of our specifications will be wider than the circle of writers. These are the programmers who will encode according to these specifications, and the testers who will then check what the programmers have coded, and even our clients who want to know as early as possible what the programmers will code for them.
Option 1. Microsoft Office.
At first glance, a simple solution. We already know how to use Word, it is installed by all programmers, so there should be no problems.
To make it easier to find the right specification, you need to have a centralized storage place for them. Create a project folder on the server with subfolders by the number of projects. We will add our documents here.
Over time, we came up with a design specification template. No, this is not a standard 20-point content that should be in any specification. God forbid. We described the design styles of different semantic parts:
- Specification Title: Subject, Author / Date / Reviewer
- Original wording / requirements from the customer
- Notes for testers
- Notes for developers - when in the text of the functional specification you need to sharpen their attention on something. If this is entirely a technical specification, for example, a description of the implementation of some tricky function on the server, or any architecture there, then we use the usual style.
- Scenario.
The useful thing turned out to be. Documents have become so fun, colorful, pleasant to read. And you can immediately find the desired part, even without reading the text, only in appearance.
')
Later it became clear that we need cross-references from one document to another. Fortunately, in Word, there is a relatively convenient mechanism for this. You can make links within the document and between documents. Over time, documents began to appear - portals, consisting mainly of links to other documents.
Sometimes (more precisely, quite often) you need to insert into the specification some kind of interface sketch, or, say, a UML diagram. We draw them in Vizio, and then we insert into the specification. The question is where do you store the files themselves? Let's come up with tricky rules - to store related files we will create a folder named like the document, and put additional materials in it.
Results:
- For half a year of work on one of our projects, about thirty full-weight specifications were generated. They were written by an analyst, a leading developer, and some ordinary developers.
- It took us:
- programs from the package MS Office, according to the number of writing specifications.
- public folder on the server for storing documents.
- Developed the rules of design and storage specifications.
Pros:
Lean curriculum curvy ((c) Golubitsky). To start the process does not require any effort other than volitional. All the necessary tools - office software and network drive - as a rule, are already available. All skills of working with documents are retained (if anyone had).
Minuses:
- Difficult to work together. If someone opened the specification, no one else can change it at this time.
- No change history. It is difficult to understand what has changed in the specification since your last reading. Even with the help of advanced Word tools - peer review, you can track only one iteration of editing a document. But at the same time, the document becomes unreadable due to underline-strikethrough and lines, notes.
- Difficult search. It is difficult to find the necessary specification, and in it - the necessary part. It is necessary to remember, at least approximately, the name of the document, and then try to find it among its fifty companions. Yes, it would seem, there is a file search in windows. But you need to do a bunch of shamanic actions, so that he began to look for office documents. And then repeat it on all thirty developers' computers.
Summary:
The described toolkit is quite sufficient when you are just starting to try your hand at specifying. It can be used in very small projects with about five developers. If you have several projects, several teams, and most importantly, you have already tasted the charms of specifications and you want more, then you need a more advanced tool. For ourselves, we found it in the wiki.
(see Part 2. Wiki - everything is at hand )
Source: https://habr.com/ru/post/85164/
All Articles