se-edu / guides

Style guides and tutorials for SE student projects
MIT License
5 stars 20 forks source link

[AB3: Tracing Code] Add more headers to section instructions #17

Open UdhayaShan1 opened 3 weeks ago

UdhayaShan1 commented 3 weeks ago

Current:

The current tutorial is a chain of many steps going up to 28 steps. It is told in the form of narration from start to finish.

Problem

It becomes challenging to link each step during tracing to the sequence diagram.

Proposed

We can add headers to highlight which logic interaction is currently being traced, for example, when LogicManager passes control to AddressBookParser, we can explicitly mention this in header in whatever is the best form. It is hoped this can allow them to relate it to the introduced sequence diagram in high level overview in #16 easily

We can also highlight it in a diagram?

drawing
damithc commented 1 week ago

@UdhayaShan1 MarkBind's image annotations feature is likely useful here. That way, we can cite the same UML diagram (directly referred from AB3) while annotating it as necessary to fit the tutorial. e.g., image

Feel free to submit a PR. Initially, the PR can add just 1-2 diagrams. After discussing the initial change set, it can proceed to add more.

UdhayaShan1 commented 1 week ago

Thanks!