Revamp Documentation

[j-lum]

Preamble

Both the User Guide and the Developer Guide has accumulated cruft over time.
Some issues include:

• Sections that students are expected to read but not maintain (e.g. Testing, Dev Ops)
• No clear separation between the various types of documentation
• Insufficient visual aids

Discussion

We need to find a way to refactor the documents such that students can find the resources that they need effectively.

According to the model proposed by Daniele Procida in his talk and accompanying article, we should divide our guides into distinct sections:

Tutorials

These are meaningful exercises that achieves a single, concrete goal. Each tutorial should be platform agnostic as much as possible to ensure that all students can replicate the tutorial successfully. Tutorials should consist of bite-sized steps with little side-effects so that students can establish a clear causality between their actions and results. Extraneous discussion should be left to other sections of the guide and alluded to briefly.

How-To Guides

These guides attempt solve common problems preemptively. Each guide should clearly outline a series of steps a student can take to achieve a specific goal but should allow some leeway so that students can adapt the guide to their own use-case. Each guide should have a clear title so that students do not have to read through an entire guide to determine its usefulness.

Reference Guides

Since we already have robust documentation in the code base, there seems to be no need for a separate document.

Further Discussion/Explanations

Optional reading that explores the rationale behind:

• Design decisions: choice of design patterns, architecture, alternatives considered
• Historical reasons: impact and implication of legacy code
• Technical constrains
  These discussions should be divorced from the code base as they serve as a contextual guide.

Proposed solution

Since AB4 is targeted at confident students who are already comfortable navigating the code base, we choose to tailor documentation for AB3.5.

Keeping in mind that both guides need to end up being collated into one file for submission:

Developer Guide

• Refactor sections that students do not need to maintain into separate documents
  • Documentation
  • Dev Ops
  • Testing
  • Discussion
• Create a landing page for the following tutorials:
  • Setting up the development environment
    Crucial for every student.
  • Enhancement of AB3.5 (Current candidate for the task is implementing the remark feature)
    This tutorial could potentially be a graded task for students to get comfortable with the code base.
  • Executing a morph of AB3.5 (Current candidate for the task is to morph AB3.5 into a to-do list app)
    Lessons learnt from past observations are that the term morph is not very well-understood and students struggle to get to a point where all of them can execute the recommended fork workflow without running into extensive merge conflicts. The deliverable at the end of the tutorial should be a cleanly refactored code base.
  • Plotting of various UML diagrams with PlantUML
    We decided upon PlantUML as it is an open-source, cross-platform tool for plotting UML diagrams that plays nice with git versioning.
• Create a landing page for the following how-to guides:
  • Adding a new UI component
    🦀UI is gone🦀 and changes to the UI are potentially gradable.
  • Packaging/usage of resources in the application JAR
    Students tend to completely forget that they eventually need to package their application into a JAR, resulting in a bit of a sticky situation just before their PE dry run.
  • Adding of dependencies
    Even though the use of external dependencies is not strongly encouraged, students should be equipped with the knowledge to consume libraries in a replicable fashion.
  • Styling of PlantUML diagrams
    Hands down one of the biggest pain points of PlantUML. Replicating the diagrams drawn in PowerPoint was a chore due to the lack of cohesiveness in the official docs. Hoping that this will alleviate some of that for the students and in turn the graders' eyesight.

[j-lum]

Taking suggestions for how-to guides since I'm sure there are other common tasks that students run into. Any criticism of the proposed solution is welcome as well!

[pyokagan]

OK, just make sure that the real underlying root causes and areas for improvement have been identified in this issue 😛 If unsure, it'll be better to do things in small steps iteratively (do a minimum viable product or something) and test it out on students. Otherwise, I'm afraid we might see a repeat of a past incident where lots of work was done and then had to be redone again... (It's not fun, kills motivation and someone would need to clean up the mess after)

Enhancement of AB3.5 (Current candidate for the task is implementing the remark feature)
This tutorial could potentially be a graded task for students to get comfortable with the code base.

Yes, this would be good.

By right, students should already have some familiarity with the codebase due to AB-2 though >:( But I guess it's not possible due to the many unnecessary differences between them.

Executing a morph of AB3.5 (Current candidate for the task is to morph AB3.5 into a to-do list app)
Lessons learnt from past observations are that the term morph is not very well-understood and students struggle to get to a point where all of them can execute the recommended fork workflow without running into extensive merge conflicts. The deliverable at the end of the tutorial should be a cleanly refactored code base.

I wouldn't recommend this. Students who are weak (who I assume this walkthrough is for) shouldn't be doing morphing in the first place, since "morphing" is technically rewriting most of the AB codebase, and is full of tedious tasks that don't teach anything about real-world software engineering at all, and will get in the way of learning software engineering concepts. Likewise, trying to describe the process would be long and tedious as well, and will be a lot of effort to write and maintain.

Plotting of various UML diagrams with PlantUML
We decided upon PlantUML as it is an open-source, cross-platform tool for plotting UML diagrams that plays nice with git versioning.

This should be in se-book, it's not specific to AB. The Developer Guide in AB can point students to se-book.

What should be in AB's developer guide is any AB-specific stuff (e.g. what settings to apply to PlantUML so that the generated images would look the same)

[j-lum]

Had a discussion with Prof @damithc where we discussed the possibility of doing away with the distinction between morphing and enhancing. Morphing seems to be a good way for them to exercise usage of automated refactoring (and discovering the pitfalls associated with that as well). Totally agree that it will be a complete PITA to maintain though.

Should probably move basic UML to se-book and the styling part of it to how-tos since it's not mandatory.

[damithc]

Had a discussion with Prof @damithc where we discussed the possibility of doing away with the distinction between morphing and enhancing. Morphing seems to be a good way for them to exercise usage of automated refactoring (and discovering the pitfalls associated with that as well). Totally agree that it will be a complete PITA to maintain though.

Agree that it is not an important SE LO. From what I'm hearing, even some weak teams appear to be taking the 'morph' option because they think it can earn them more marks, and then getting stuck in that step for too long. It may be useful if we can prescribe a shortest-path way to do a quick morph with minimum fuss. To that end, I'm interested to know how much work it is to do a minimal morph of AB3.5 from Person to Task with full use of IDE automation. It's minimal in the sense that things like renaming/adding/deleting attributes are not covered (those things can be separate tutorials as they are useful even if the team is not morphing).
That means, if we eventually end up providing such a tutorial, it would be written in tutorial style but unlikely to be made a tutorial task that everyone needs to do. Instead, it would be something like if you plan to do a morph, we recommend one team member do the initial morphing very early in the project by following this guide.

[pyokagan]

To that end, I'm interested to know how much work it is to do a minimal morph of AB3.5 from Person to Task with full use of IDE automation.

Yes, let's go collect some data first.

It might be the case that the AB's original goal of simulating a realistic real-world application so that students know how to work with a big codebase, and the goal of being easy to morph, are fundamentally opposed to each other though, since so much code sits on top of AB's model as a result. If that turns out to be true, a better way would be to have an AB-3 and a "AB-3 skeleton", which is AB-3's architecture stripped out of all domain objects (i.e. an empty Model, save maybe a few domain objects if teaching students how to rename stuff is really needed).