How I document the development process.
Do you write extra documentation for your project? Not? Then it is probably not enough for you.
To guess for each specific project the required amount of technical documentation is extremely difficult and important. It is important - because the process speed, quality and cost depend on it. It is difficult - because the process itself may change over time, the performers may change, and for a given state of the process it is not so easy to select the necessary set and volume of documentation.
Here I would like to talk about my approach to documenting work on small projects. A small project is: the head-analyst, 1-3 developers, tester. Or any similar composition. By documentation, I mean 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 record the results of all negotiations. It takes a minute, but allows you to continue to answer such questions: "Why did we need it?", "Why do we not need it now?". The first group of questions may arise when the jambs are in the analytical part or because of a return to some old functionality. The second group of questions allows you to make decisions with greater certainty at turning points.
On github, I created a “Meeting minutes” page in wiki in which I record the results of the discussion in chronological order. I specify the date and subject 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 keep one message that I edit and ask for confirmation. I copy on github together with confirmation. The average recording volume for one discussion is 5-10 lines.
Here is a little more complicated. I fix: user interface, subject area, text of requirements for each iteration.
User Interface - I use AxureRP. I document in detail - up to a button, add page navigation dynamics, update parts of pages. It helps to speed up the delivery of tasks to developers, to identify their own mistakes in designing solutions for the desired user scenarios. I publish interfaces for sharing and use links to the necessary pages in the requirements and discussions. Very comfortably. Interfaces are updated immediately after each change.
Here is the most common my prototype interface:
Subject area - I use Enterprise Architect only as an ER-chart renderer. This stage is very important for me, because on it I catch a lot of proposals to change the proposed implementation, which will allow to obtain certain advantages in the future, think through data storage structures, etc. In very small projects I often omit this component. I publish pictures of the obtained diagrams together with the prototypes on axshare and also give links to them in the tasks for iteration or in discussions in Skype so that developers can better understand the task or to substantively discuss the problem with the interested person. It is also very convenient to give a link to the diagram directly from the prototype of the user interface, so that the developer does not lose context when reading the requirements.
Requirements - I am writing immediately on github. On the github in the wiki, I made a separate page, on which all changes are contained in chronological order (respectively, all iterations). I use references to prototypes and domain diagrams. I describe only the logic. If you write more and more, the costs of maintaining the documentation increase dramatically. The average volume of 4-5 paragraphs of 1-10 lines. Iterations we usually 3-10 days.
This approach allows you to see on one page the entire chronology of iterations and analytics and the developer . Also, which is very important, I use the same page to record plans for the next iterations. I highlight the current iteration either in color or just in bold text. Sometimes I specify the dates of the fact / plan for the dates of the beginning and end of the iteration. The further the planned iteration from the current, the more concise the statement, the closer the more detailed. I use descriptions of future iterations to discuss with developers and other participants in the process.
A typical example of requirements for iteration:
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 interface design and up to 1 hour for a text description of the requirements.
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:
Creature. The analyst makes a task (bug or enhancement), optionally indicates if the error on the battle and on the test is not there - as (prod), and optionally indicates if it is urgently necessary to fix it (A).
Work The developer checks whether the task is labeled (A). If there is takes it, if not takes the next one. It reads and either corrects (need upload), or says that it cannot reproduce (can't reproduce), or need more information (need info).
Information If the response is needed, the Analytics responds in kamentah and removes (can't reproduce / need info) or closes the task.
Work Developer corrects if the task is not removed and puts (need upload).
Filling for test Razrbaotchik fills, removes need uplaod, puts fixed on what is uploaded to the test server. If the bug is specified from the combat one, the Developer does not put fixed until there are no changes in the combat one.
Testing on the test Tester watch and either close the task, or leave it open and remove fixed.
Fill to the combat Developer, uploads to the combat: - all closed, which are fixed (remove fixed) - all open ones that have (prod) and (need upload).
Testing on the battle Tester is testing those bugs that are (prod) and (fixed), if everything is OK, then close the task.
* I have the real names of the developers and other participants in the process. It helps.
It's all very mundane. I use github.
I have come to this format of work for several years of work as an analyst / project manager, working on both automation projects for small enterprises and ordinary Internet services. The foregoing, perhaps trite, but it really saves time, allowing the whole team to keep abreast of events and not to waste time supporting extra documents.
Thank.
To guess for each specific project the required amount of technical documentation is extremely difficult and important. It is important - because the process speed, quality and cost depend on it. It is difficult - because the process itself may change over time, the performers may change, and for a given state of the process it is not so easy to select the necessary set and volume of documentation.
Here I would like to talk about my approach to documenting work on small projects. A small project is: the head-analyst, 1-3 developers, tester. Or any similar composition. By documentation, I mean 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 record the results of all negotiations. It takes a minute, but allows you to continue to answer such questions: "Why did we need it?", "Why do we not need it now?". The first group of questions may arise when the jambs are in the analytical part or because of a return to some old functionality. The second group of questions allows you to make decisions with greater certainty at turning points.
On github, I created a “Meeting minutes” page in wiki in which I record the results of the discussion in chronological order. I specify the date and subject 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 keep one message that I edit and ask for confirmation. I copy on github together with confirmation. The average recording volume for one discussion is 5-10 lines.
Requirements
Here is a little more complicated. I fix: user interface, subject area, text of requirements for each iteration.
User Interface - I use AxureRP. I document in detail - up to a button, add page navigation dynamics, update parts of pages. It helps to speed up the delivery of tasks to developers, to identify their own mistakes in designing solutions for the desired user scenarios. I publish interfaces for sharing and use links to the necessary pages in the requirements and discussions. Very comfortably. Interfaces are updated immediately after each change.
Here is the most common my prototype interface:
Subject area - I use Enterprise Architect only as an ER-chart renderer. This stage is very important for me, because on it I catch a lot of proposals to change the proposed implementation, which will allow to obtain certain advantages in the future, think through data storage structures, etc. In very small projects I often omit this component. I publish pictures of the obtained diagrams together with the prototypes on axshare and also give links to them in the tasks for iteration or in discussions in Skype so that developers can better understand the task or to substantively discuss the problem with the interested person. It is also very convenient to give a link to the diagram directly from the prototype of the user interface, so that the developer does not lose context when reading the requirements.
Requirements - I am writing immediately on github. On the github in the wiki, I made a separate page, on which all changes are contained in chronological order (respectively, all iterations). I use references to prototypes and domain diagrams. I describe only the logic. If you write more and more, the costs of maintaining the documentation increase dramatically. The average volume of 4-5 paragraphs of 1-10 lines. Iterations we usually 3-10 days.
This approach allows you to see on one page the entire chronology of iterations and analytics and the developer . Also, which is very important, I use the same page to record plans for the next iterations. I highlight the current iteration either in color or just in bold text. Sometimes I specify the dates of the fact / plan for the dates of the beginning and end of the iteration. The further the planned iteration from the current, the more concise the statement, the closer the more detailed. I use descriptions of future iterations to discuss with developers and other participants in the process.
A typical example of requirements for iteration:
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 interface design and up to 1 hour for a text description of the requirements.
Changes
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:
Creature. The analyst makes a task (bug or enhancement), optionally indicates if the error on the battle and on the test is not there - as (prod), and optionally indicates if it is urgently necessary to fix it (A).
Work The developer checks whether the task is labeled (A). If there is takes it, if not takes the next one. It reads and either corrects (need upload), or says that it cannot reproduce (can't reproduce), or need more information (need info).
Information If the response is needed, the Analytics responds in kamentah and removes (can't reproduce / need info) or closes the task.
Work Developer corrects if the task is not removed and puts (need upload).
Filling for test Razrbaotchik fills, removes need uplaod, puts fixed on what is uploaded to the test server. If the bug is specified from the combat one, the Developer does not put fixed until there are no changes in the combat one.
Testing on the test Tester watch and either close the task, or leave it open and remove fixed.
Fill to the combat Developer, uploads to the combat: - all closed, which are fixed (remove fixed) - all open ones that have (prod) and (need upload).
Testing on the battle Tester is testing those bugs that are (prod) and (fixed), if everything is OK, then close the task.
* I have the real names of the developers and other participants in the process. It helps.
Code Versions
It's all very mundane. I use github.
Conclusion
I have come to this format of work for several years of work as an analyst / project manager, working on both automation projects for small enterprises and ordinary Internet services. The foregoing, perhaps trite, but it really saves time, allowing the whole team to keep abreast of events and not to waste time supporting extra documents.
Thank.
Source: https://habr.com/ru/post/244247/
All Articles