Answers.Body: <p>Agile doesn't mean "don't plan", so there should be plenty to talk about.</p>
  
  <p>Have your students developed <a href="http://www.extremeprogramming.org/rules/userstories.html" rel="nofollow noreferrer">user stories</a>? Can they talk about these? For example, let's take this example user story:</p>
  
  <blockquote>
    <p>As a teacher, I want to automatically mark assignments so I'm not spending time checking code that could be done automatically.</p>
  </blockquote>
  
  <p>It might be worthwhile to encourage your students to consider how and why they wrote their user stories as they did. You can check that they're not developing user stories that are too broad (<a href="https://www.mountaingoatsoftware.com/blog/stories-epics-and-themes" rel="nofollow noreferrer">too many epics</a> rather than stories) as they go along if you want to provide some support and prevent them from being too unrealistic.</p>
  
  <p>As you should probably be estimating the amount of work for each user story, ask them to document that so you can check it. Unrealistic timings—or no timings at all—should be caught early so that you can make sure they finish the project on time. </p>
  
  <p>If you follow the '<a href="https://en.wikipedia.org/wiki/Extreme_programming_practices#Release_planning" rel="nofollow noreferrer">planning game</a>' of XP, then you can also look at how the requirements were sorted by risk and value. Yet another point to document and mark if needed.</p>
  
  <p>As mentioned by <a href="https://cseducators.stackexchange.com/a/1473/2">Kaneki</a>, sprint retrospectives provide time for your students to reflect on their progress. Encourage them to use this wisely in place of a huge specification detailing implementations, tests, etc. </p>
  
  <p>In short, there's <strong>loads</strong> to document about Agile, but you might not need to write everything on paper. If it's easier for you, consider just being a part of the retrospective meetings and looking at how these go instead of meticulously writing down every detail. </p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:02:48.627Z
Answers.Text: I agree. The thing is the final report should reflect all the work that the student has done during the internship. Someone that didn´t follow his/her work should also be able to understand it simply by reading the report.
Answers.UserDisplayName: Nuno Gil Fonseca
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:07:32.737Z
Answers.Text: @NunoGilFonseca I think with the user stories, planning and retrospectives, you should cover practically everything of interest. Is it a strict requirement that **absolutely everything** is covered, or could you just encourage your students to update their retrospective document at the end of every sprint reflecting on their work personally, along with the usual Agile processes?
Answers.UserDisplayName: Aurora0001
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:21:09.120Z
Answers.Text: Our main problem is that right now there is not a formal clarification of what must be covered... :(
Answers.UserDisplayName: Nuno Gil Fonseca
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T14:57:23.380Z
Answers.LastActivityDate: 2017-07-07T14:57:23.380Z
Answers.UserDisplayName: Aurora0001
Answers.Body: <p>If the system is object-oriented, you can use UML class diagrams to document the design. Eclipse has a plugin called <a href="http://www.objectaid.com/" rel="nofollow noreferrer">ObjectAid</a> that generates these diagrams from the source code (no additional work required).</p>
  
  <p>Students can generate professional documentation from their source code. There is <a href="https://www.npmjs.com/package/jsdoc" rel="nofollow noreferrer">jsdoc</a> for JavaScript and <a href="https://www.tutorialspoint.com/java/java_documentation.htm" rel="nofollow noreferrer">javadoc</a> for Java. These require specific comments and tags, but it's well worth it. Source code documentation is important for future development.</p>
  
  <p>For all types of diagrams, there's <a href="https://www.draw.io/" rel="nofollow noreferrer">draw.io</a>, <a href="https://balsamiq.com/" rel="nofollow noreferrer">Balsamiq</a>, PowerPoint, Visio, and many more. A picture is worth a thousand words.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:13:34.193Z
Answers.Text: I am aware of that! And they do all of that during the development. My question was more focused on what and how should that info be integrated into one "thesis-like" report.
Answers.UserDisplayName: Nuno Gil Fonseca
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:22:22.803Z
Answers.Text: It depends on the target audience. System architecture diagrams work well as figures in an overview section, for all audiences. Developers might want to see UML class diagrams or excerpts from generated documentation in a software design section. I would also include a requirements section, to convey the capabilities of the software. A requirements traceability matrix (RTM) works well.
Answers.UserDisplayName: Edwin Torres
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:07:53.213Z
Answers.LastActivityDate: 2017-07-07T15:07:53.213Z
Answers.UserDisplayName: Edwin Torres
Answers.Body: <p>In SCRUM, during the end of each sprint, there is a <b>Sprint Retrospective</b> and <b>Spring Review</b>. Important artifacts from the two should be extracted into this report, as it reflects the "developed work".</p>
  
  <p>I'm not sure the scope of what you require from your students for documenting the work, is it for the whole internship, or just one cycle? In any case, because Agile is done incrementally, they can just write one template per sprint they've completed.</p>
  
  <ul>
  <li>Sprint Number</li>
  <li>Sprint velocity</li>
  <li>List of stories completed</li>
  <li>Did it meet success criteria (definition of done and agile manifesto)</li>
  <li>Notes from sprint review</li>
  <li>Notes from sprint retrospective</li>
  <li>Implementation strategies (if it is required by you)</li>
  <li>...</li>
  </ul>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T14:59:09.267Z
Answers.Text: The final report should reflect all the work that the student has done during the internship. Someone that didn´t follow his/her work should be able to understand it simply by reading the report. What you are suggesting is also what I think is right. Some of my colleagues think that there should be some kind of a centralized list of requirements... :(
Answers.UserDisplayName: Nuno Gil Fonseca
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T15:03:24.247Z
Answers.Text: Ah I see. Even in the industry today, it is hard to convince some old timers of the new age of Agile :P If your colleagues don't want to add a new list for students in an Agile environment, then perhaps just add these new requirements and word it as "answer all that apply"? Judging Agile with Waterfall is like judging a tutle for his ability to climb a tree.
Answers.UserDisplayName: Kaneki
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-07-07T14:50:38.510Z
Answers.LastActivityDate: 2017-07-07T14:50:38.510Z
Answers.UserDisplayName: Kaneki
Body: <p>In the final report of their internship, the students of our school must have one chapter where they "document" the developed work. When using the “waterfall” methodology, they usually have one sub-section for each stage: </p>
  
  <ul>
  <li>requirements</li>
  <li>detailed design</li>
  <li>implementation</li>
  <li>tests</li>
  <li>...</li>
  </ul>
  
  <p>What if an agile methodology like XP or SCRUM is used? Every year we have the same problem, as some teachers say it should be done one way, while others say the exact opposite. </p>
  
  <p>Any ideas?</p>
  
Tags: <agile-development><documentation>
Title: How to document the developed work using an agile methodology?
ThreadText: # How to document the developed work using an agile methodology?
  
  (Asked by: username_0 on 2017-07-07)
  
  In the final report of their internship, the students of our school must have one chapter where they "document" the developed work. When using the “waterfall” methodology, they usually have one sub-section for each stage:
  
  * requirements
  * detailed design
  * implementation
  * tests
  * ...
  
  What if an agile methodology like XP or SCRUM is used? Every year we have the same problem, as some teachers say it should be done one way, while others say the exact opposite.
  
  Any ideas?
  
  **Tags:** agile-development, documentation
  
  
  ---
  
  ## 3 answers
  
  ### Answer by username_3 on 2017-07-07. Score: 2
  
  In SCRUM, during the end of each sprint, there is a **Sprint Retrospective** and **Spring Review**. Important artifacts from the two should be extracted into this report, as it reflects the "developed work".
  
  I'm not sure the scope of what you require from your students for documenting the work, is it for the whole internship, or just one cycle? In any case, because Agile is done incrementally, they can just write one template per sprint they've completed.
  
  * Sprint Number
  * Sprint velocity
  * List of stories completed
  * Did it meet success criteria (definition of done and agile manifesto)
  * Notes from sprint review
  * Notes from sprint retrospective
  * Implementation strategies (if it is required by you)
  * ...
  
  > **Comments:**
  > **username_0**: The final report should reflect all the work that the student has done during the internship. Someone that didn´t follow his/her work should be able to understand it simply by reading the report. What you are suggesting is also what I think is right. Some of my colleagues think that there should be some kind of a centralized list of requirements... :(  
  > **username_3**: Ah I see. Even in the industry today, it is hard to convince some old timers of the new age of Agile :P If your colleagues don't want to add a new list for students in an Agile environment, then perhaps just add these new requirements and word it as "answer all that apply"? Judging Agile with Waterfall is like judging a tutle for his ability to climb a tree.  
  
  ---
  
  ### Answer by username_1 on 2017-07-07. Score: 1
  
  Agile doesn't mean "don't plan", so there should be plenty to talk about.
  
  Have your students developed [user stories](http://www.extremeprogramming.org/rules/userstories.html)? Can they talk about these? For example, let's take this example user story:
  
  > As a teacher, I want to automatically mark assignments so I'm not spending time checking code that could be done automatically.
  
  It might be worthwhile to encourage your students to consider how and why they wrote their user stories as they did. You can check that they're not developing user stories that are too broad ([too many epics](https://www.mountaingoatsoftware.com/blog/stories-epics-and-themes) rather than stories) as they go along if you want to provide some support and prevent them from being too unrealistic.
  
  As you should probably be estimating the amount of work for each user story, ask them to document that so you can check it. Unrealistic timings—or no timings at all—should be caught early so that you can make sure they finish the project on time.
  
  If you follow the '[planning game](https://en.wikipedia.org/wiki/Extreme_programming_practices#Release_planning)' of XP, then you can also look at how the requirements were sorted by risk and value. Yet another point to document and mark if needed.
  
  As mentioned by [username_3](https://cseducators.stackexchange.com/a/1473/2), sprint retrospectives provide time for your students to reflect on their progress. Encourage them to use this wisely in place of a huge specification detailing implementations, tests, etc.
  
  In short, there's **loads** to document about Agile, but you might not need to write everything on paper. If it's easier for you, consider just being a part of the retrospective meetings and looking at how these go instead of meticulously writing down every detail.
  
  > **Comments:**
  > **username_0**: I agree. The thing is the final report should reflect all the work that the student has done during the internship. Someone that didn´t follow his/her work should also be able to understand it simply by reading the report.  
  > **username_1**: @username_0 I think with the user stories, planning and retrospectives, you should cover practically everything of interest. Is it a strict requirement that **absolutely everything** is covered, or could you just encourage your students to update their retrospective document at the end of every sprint reflecting on their work personally, along with the usual Agile processes?  
  > **username_0**: Our main problem is that right now there is not a formal clarification of what must be covered... :(  
  
  ---
  
  ### Answer by username_2 on 2017-07-07. Score: 0
  
  If the system is object-oriented, you can use UML class diagrams to document the design. Eclipse has a plugin called [ObjectAid](http://www.objectaid.com/) that generates these diagrams from the source code (no additional work required).
  
  Students can generate professional documentation from their source code. There is [jsdoc](https://www.npmjs.com/package/jsdoc) for JavaScript and [javadoc](https://www.tutorialspoint.com/java/java_documentation.htm) for Java. These require specific comments and tags, but it's well worth it. Source code documentation is important for future development.
  
  For all types of diagrams, there's [draw.io](https://www.draw.io/), [Balsamiq](https://balsamiq.com/), PowerPoint, Visio, and many more. A picture is worth a thousand words.
  
  > **Comments:**
  > **username_0**: I am aware of that! And they do all of that during the development. My question was more focused on what and how should that info be integrated into one "thesis-like" report.  
  > **username_2**: It depends on the target audience. System architecture diagrams work well as figures in an overview section, for all audiences. Developers might want to see UML class diagrams or excerpts from generated documentation in a software design section. I would also include a requirements section, to convey the capabilities of the software. A requirements traceability matrix (RTM) works well.  
  
  ---
  
  