66 lines
4 KiB
Markdown
66 lines
4 KiB
Markdown
|
## Peer Reflection on UML Diagram
|
||
|
|
|
||
|
|
The learning objectives:
|
||
|
|
|
||
|
|
- Reflect on methods for communicating code structure.
|
||
|
|
- Critically analyze the UML diagram as written communication.
|
||
|
|
- Identify the key characteristics of this writing form that best communicate code structure for the purpose of assisting others in understanding the code.
|
||
|
|
- Identify strengths and weaknesses of your UML and paragraph drafts.
|
||
|
|
|
||
|
|
### _Good_ Writing Criteria
|
||
|
|
|
||
|
|
- States key information clearly (important findings, recommendations, ideas,
|
||
|
|
issues, etc.).
|
||
|
|
- Addresses target audience with an appropriate tone and level of explanation.
|
||
|
|
- Presents any needed background explanation clearly or informatively.
|
||
|
|
- Describes algorithms, data structures, software system components, etc.
|
||
|
|
accurately.
|
||
|
|
- Describes algorithms, data structures, software system components, etc.
|
||
|
|
informatively and concisely.
|
||
|
|
- Uses terminology and notation correctly.
|
||
|
|
- Uses appropriate structures (lists, diagrams, equations, code samples, etc.).
|
||
|
|
- Includes clear and informative tables, diagrams, references, etc.
|
||
|
|
- Has a good organization and logical flow.
|
||
|
|
- Avoids including irrelevant information, overemphasizing less important material,
|
||
|
|
or writing verbosely.
|
||
|
|
|
||
|
|
## Form a Group
|
||
|
|
|
||
|
|
Form a group of 3 to 4 people. Not 2 and not more than 4. Someone volunteer to start.
|
||
|
|
|
||
|
|
> Take personal notes during the discussion to use to improve your UML, as well as develop the main page of doxygen documentation for next week's submission.
|
||
|
|
|
||
|
|
### Each person ...
|
||
|
|
|
||
|
|
1. Show your UML diagram and paragraph to the group, giving everyone a few minutes to look it over and read the paragraph.
|
||
|
|
|
||
|
|
2. Explain your process in understanding the code structure and creating your UML diagram. Did you spend hours with the code then start your UML? Did you start with the UML and fill it in as your understanding of the code grew?
|
||
|
|
|
||
|
|
3. State what tool you used. What was the good and bad of that tool? Would you recommend that tool to others?
|
||
|
|
|
||
|
|
4. Look at the UML and paragraph as a unit. In what ways does the paragraph enhance or complement the UML? In what ways does the UML complement the paragraph?
|
||
|
|
|
||
|
|
5. Share with peers what you found to be the most difficult aspect of generating the diagram.
|
||
|
|
|
||
|
|
6. Share with the group something you want to improve upon in the diagram or the paragraph.
|
||
|
|
|
||
|
|
### Next (after everyone shared) ...
|
||
|
|
|
||
|
|
Collectively discuss the following:
|
||
|
|
|
||
|
|
1. MEDIUM: Identify elements in each UML that is unique and brings value to understanding the code. (Keep this in mind as you edit your UML for next week's submission).
|
||
|
|
|
||
|
|
2. DETAIL: Compare the levels of detail on each UML. Is there huge variety? Identify places in each UML where you think either more or less detail is needed.
|
||
|
|
|
||
|
|
3. AUDIENCE: Would you change the level of detail for different audiences? For example, as someone who is now submerged in the code, do you want more or less detail? Think back to when you didn't know the code - do you think you want more or less detail?
|
||
|
|
|
||
|
|
3. VISUALIZATION: Compare the overall layouts and formatting for each. Is there huge variety? Do fonts make a difference? Can you distinguish arrows? Identify places in each UML where layout or formatting could be improved.
|
||
|
|
|
||
|
|
4. CORRECTNESS: Are things presented correctly - inheritance, composition, flow-of-information?
|
||
|
|
|
||
|
|
5. WRITING PROCESS: How much do you think the UML contributes to understanding the code OR is it the _process_ of constructing the UML that is the most informative? What is your opinion on the utility of an auto-generated UML (which doxygen will do for you)?
|
||
|
|
|
||
|
|
5. COMPLETENESS: Think back to when you first engaged the code. What was missing from what was provided to you to better assist you in understanding the code (other than the UML)? How can you incorporate those elements into either the UML or in the mainpage of your doxygen documentation?
|
||
|
|
|
||
|
|
6. DOCUMENTATION PLAN: Collectively establish a rough outline of content for the doxygen documentation. This is an introduction to the project and to the html pages. Keep in mind your audience. Level of detail is important - how much detail do you need to go into?
|