How do I document the development process
Are you writing extra documentation for your project? Not? Then it is most likely not enough for you.
It is extremely difficult and important to guess for each specific project the necessary amount of technical documentation. It is important because the speed of the process, quality and cost depend on it. It is difficult - because the process itself can change over time, the executors can change, and for a given state of the process it is not so easy to choose the right set and amount of documentation.
Here I would like to talk about my approach to documenting work on small projects. A small project is: an analyst leader, 1-3 developers, a tester. Or some similar composition. By documentation I understand any artifacts created to support the following processes: discussions, requirements management, change management, version control. I do not document other processes.
I use Enterprise Architect, AxureRP, Github, Skype. It's all.
I fix the results of all negotiations. It takes a minute, but allows you to answer questions such as: “Why did we need this?”, “Why do we not need it now?”. The first group of questions may arise with jambs in the analytical part or because of a return to some old functionality. The second group of questions allows you to make decisions with more confidence at turning points.
On github, I created a meeting minutes page on the wiki, in which I write down the discussion results in chronological order. I indicate the date and subject of discussion in the title. I write immediately on github. Thus I have one page with the results of all discussions. If the discussion was text in Skype, then in Skype I’m writing one message that I’m editing and asking for confirmation. I copy to github along with the confirmation. The average recording volume per discussion is 5-10 lines.
This is a bit trickier. I commit: user interface, subject area, requirements text for each iteration.
User Interface - using AxureRP. I document in detail - up to a button, add the dynamics of page transitions, updating parts of pages. It helps a lot to speed up the delivery of tasks to developers, to identify their own mistakes in designing a solution for the right user scenarios. I publish interfaces for sharing and use links to the necessary pages in the requirements and discussions. Very comfortably. I update the interfaces immediately after each change.
Here is the most common interface my prototype:
Specialization- I use Enterprise Architect only as a drawing of ER-diagrams. This stage is very important for me, because on it I catch a lot of suggestions for changing the proposed implementation, which will allow me to get certain advantages in the future, I think through the structure of data storage, etc. In very small projects, I often omit this component. I publish pictures of the resulting diagrams along with axshare prototypes and also provide links to them in iteration assignments or in discussions on Skype in order for developers to better understand the task or to discuss the problem in detail with an interested person. It is also very convenient directly from the prototype user interface to provide a link to the diagram so that the developer does not lose context when reading requirements.
Requirements- I write immediately on github. On github in the wiki, I made a separate page on which all changes (respectively, all iterations) are contained in a chronological order . I use links to prototypes and domain diagrams. I describe only the logic. If you write more and in more detail, then the cost of maintaining documentation increases sharply. The average volume of 4-5 paragraphs of 1-10 lines. Iterations are usually 3-10 days.
This approach allows you to see the whole iteration chronology and analytics and developer on one page. Also, which is very important, I use the same page to record plans for the next iteration. I highlight the current iteration with either color or just bold text. Sometimes I indicate the fact / plan dates of the start and end dates of the iteration. The farther the planned iteration from the current, the more abstract the presentation, the closer the more detailed. I use the descriptions of future iteration for discussion with developers and other participants in the process.
A typical example of iteration requirements: I
calculated that on average it takes 2-3 hours to document the requirements for iteration (on average once a week): 1 hour for the subject area, 1 for the design of interfaces and up to 1 hour for a textual description of the requirements.
The changes identified two types: bug and enchencement. As a tracker, I use the same github. Over time, I came to the following set of task labels:
And to the following rules for affixing statuses:
Creation. The analyst does the task (bug or enhancement), optionally indicates if the error is on the battlefield and on the test it is not (prod), and optionally indicates if the correction needs to be urgently (A).
Work The developer checks if there are no tasks with a tag (A). If there is takes it, if not takes it next. It reads and either corrects (need upload), or says that it cannot reproduce (can't reproduce), or it needs more information (need info).
Information If a reaction is needed Analytics answers in comments and removes (can't reproduce / need info) or closes the task.
Work The developer corrects if the task is not removed and sets (need upload).
Pouring for the test The developer pours, removes the need uplaod, sets fixed to what is uploaded to the test server. If the bug is specified from the battle one, then the Developer does not set fixed until there are changes to the battle one.
Testing on the test The tester looks and either close the task or leave it open and removes fixed.
Fill on the battle Developer pours on the battle: - all closed, which are fixed (at the same time remove fixed) - all open which have (prod) and (need upload).
Check on the battle The tester tests those bugs that are (prod) and (fixed), if everything is OK then close the task.
* I have the real names of developers and other process participants in the wiki. It helps.
Everything is quite ordinary here. I'm using github.
I came to this format of work for several years of working as an analyst / project manager, working both on automation projects for small enterprises and conventional Internet services. The above may be trite, but it really saves time, allowing the whole team to keep abreast of events and not lose time supporting unnecessary documents.
Thanks.
It is extremely difficult and important to guess for each specific project the necessary amount of technical documentation. It is important because the speed of the process, quality and cost depend on it. It is difficult - because the process itself can change over time, the executors can change, and for a given state of the process it is not so easy to choose the right set and amount of documentation.
Here I would like to talk about my approach to documenting work on small projects. A small project is: an analyst leader, 1-3 developers, a tester. Or some similar composition. By documentation I understand any artifacts created to support the following processes: discussions, requirements management, change management, version control. I do not document other processes.
Tools
I use Enterprise Architect, AxureRP, Github, Skype. It's all.
Discussions
I fix the results of all negotiations. It takes a minute, but allows you to answer questions such as: “Why did we need this?”, “Why do we not need it now?”. The first group of questions may arise with jambs in the analytical part or because of a return to some old functionality. The second group of questions allows you to make decisions with more confidence at turning points.
On github, I created a meeting minutes page on the wiki, in which I write down the discussion results in chronological order. I indicate the date and subject of discussion in the title. I write immediately on github. Thus I have one page with the results of all discussions. If the discussion was text in Skype, then in Skype I’m writing one message that I’m editing and asking for confirmation. I copy to github along with the confirmation. The average recording volume per discussion is 5-10 lines.
Requirements
This is a bit trickier. I commit: user interface, subject area, requirements text for each iteration.
User Interface - using AxureRP. I document in detail - up to a button, add the dynamics of page transitions, updating parts of pages. It helps a lot to speed up the delivery of tasks to developers, to identify their own mistakes in designing a solution for the right user scenarios. I publish interfaces for sharing and use links to the necessary pages in the requirements and discussions. Very comfortably. I update the interfaces immediately after each change.
Here is the most common interface my prototype:
Specialization- I use Enterprise Architect only as a drawing of ER-diagrams. This stage is very important for me, because on it I catch a lot of suggestions for changing the proposed implementation, which will allow me to get certain advantages in the future, I think through the structure of data storage, etc. In very small projects, I often omit this component. I publish pictures of the resulting diagrams along with axshare prototypes and also provide links to them in iteration assignments or in discussions on Skype in order for developers to better understand the task or to discuss the problem in detail with an interested person. It is also very convenient directly from the prototype user interface to provide a link to the diagram so that the developer does not lose context when reading requirements.
Requirements- I write immediately on github. On github in the wiki, I made a separate page on which all changes (respectively, all iterations) are contained in a chronological order . I use links to prototypes and domain diagrams. I describe only the logic. If you write more and in more detail, then the cost of maintaining documentation increases sharply. The average volume of 4-5 paragraphs of 1-10 lines. Iterations are usually 3-10 days.
This approach allows you to see the whole iteration chronology and analytics and developer on one page. Also, which is very important, I use the same page to record plans for the next iteration. I highlight the current iteration with either color or just bold text. Sometimes I indicate the fact / plan dates of the start and end dates of the iteration. The farther the planned iteration from the current, the more abstract the presentation, the closer the more detailed. I use the descriptions of future iteration for discussion with developers and other participants in the process.
A typical example of iteration requirements: I
calculated that on average it takes 2-3 hours to document the requirements for iteration (on average once a week): 1 hour for the subject area, 1 for the design of interfaces and up to 1 hour for a textual description of the requirements.
Changes
The changes identified two types: bug and enchencement. As a tracker, I use the same github. Over time, I came to the following set of task labels:
And to the following rules for affixing statuses:
Creation. The analyst does the task (bug or enhancement), optionally indicates if the error is on the battlefield and on the test it is not (prod), and optionally indicates if the correction needs to be urgently (A).
Work The developer checks if there are no tasks with a tag (A). If there is takes it, if not takes it next. It reads and either corrects (need upload), or says that it cannot reproduce (can't reproduce), or it needs more information (need info).
Information If a reaction is needed Analytics answers in comments and removes (can't reproduce / need info) or closes the task.
Work The developer corrects if the task is not removed and sets (need upload).
Pouring for the test The developer pours, removes the need uplaod, sets fixed to what is uploaded to the test server. If the bug is specified from the battle one, then the Developer does not set fixed until there are changes to the battle one.
Testing on the test The tester looks and either close the task or leave it open and removes fixed.
Fill on the battle Developer pours on the battle: - all closed, which are fixed (at the same time remove fixed) - all open which have (prod) and (need upload).
Check on the battle The tester tests those bugs that are (prod) and (fixed), if everything is OK then close the task.
* I have the real names of developers and other process participants in the wiki. It helps.
Code Versions
Everything is quite ordinary here. I'm using github.
Conclusion
I came to this format of work for several years of working as an analyst / project manager, working both on automation projects for small enterprises and conventional Internet services. The above may be trite, but it really saves time, allowing the whole team to keep abreast of events and not lose time supporting unnecessary documents.
Thanks.