3
$\begingroup$

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?

$\endgroup$
2
$\begingroup$

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)
  • ...
| improve this answer | |
$\endgroup$
  • $\begingroup$ 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... :( $\endgroup$ – Nuno Gil Fonseca Jul 7 '17 at 14:59
  • $\begingroup$ 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. $\endgroup$ – Kaneki Jul 7 '17 at 15:03
1
$\begingroup$

Agile doesn't mean "don't plan", so there should be plenty to talk about.

Have your students developed user stories? 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 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' 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 Kaneki, 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.

| improve this answer | |
$\endgroup$
  • $\begingroup$ 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. $\endgroup$ – Nuno Gil Fonseca Jul 7 '17 at 15:02
  • $\begingroup$ @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? $\endgroup$ – Aurora0001 Jul 7 '17 at 15:07
  • $\begingroup$ Our main problem is that right now there is not a formal clarification of what must be covered... :( $\endgroup$ – Nuno Gil Fonseca Jul 7 '17 at 15:21
0
$\begingroup$

If the system is object-oriented, you can use UML class diagrams to document the design. Eclipse has a plugin called ObjectAid that generates these diagrams from the source code (no additional work required).

Students can generate professional documentation from their source code. There is jsdoc for JavaScript and javadoc 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, Balsamiq, PowerPoint, Visio, and many more. A picture is worth a thousand words.

| improve this answer | |
$\endgroup$
  • $\begingroup$ 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. $\endgroup$ – Nuno Gil Fonseca Jul 7 '17 at 15:13
  • $\begingroup$ 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. $\endgroup$ – Edwin Torres Jul 7 '17 at 15:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.