User guide revamp

[j-lum]

The current UG is missing critical section(s) and needs to be fleshed out. According to principles outlined in this article, proper documentation should consist of several distinct sections to address the different needs of users.

For AB4, the UG should consist of:

1. A laser-focused tutorial that gets a user from zero to accomplishing their first task with the AB.
2. Several how-to guides that will guide users through several broader, common use cases.
3. A reference section that offers in-depth overview for each command.

The number of visual aids should also be increased to enhance readability. As it is, the whole UG only has one image in the header and users might have a hard time following through guide.

[pyokagan]

The number of visual aids should also be increased to enhance readability. As it is, the whole UG only has one image in the header and users might have a hard time following through guide.

We don't have any users, only students, so for the sake of clarification I'll ask: what's the true objective of revamping the User Guide (keeping in mind that AB-4 is a teaching tool?) Will the same revamps be done to AB-1, AB-2 and AB-3?

[damithc]

Objective: the provided UG is supposed to be the 'model solution' that students follow when students write UG for their own feature. I would like the model solution to contain a sufficient level of visuals so that students will naturally include the same level of visuals.

Having said that, should we do this at AB-3? Previously we decided to do all changes at AB-4 and then backport to AB-3 but this change is unlikely to be able to backport as the visuals are going to be GUI specific.

[pyokagan]

For screenshots of the GUI, do ensure that the steps to reproduce them are documented. Most importantly: the window dimensions for taking the screenshot. No MacOS please, no developer would want to buy an entire machine for AB. Preferably Windows 10. (With cost in mind, Linux would be the best choice, but I understand that Windows is more popular ;-) )

[pyokagan]

Having said that, should we do this at AB-3?

Depending on how greatly the UG is revamped, the danger of this is that if there are any changes to AB-4's UG in the future (if we still maintain it ;-) ), it would be unclear how such a change would apply to AB-3's UG. This may cause AB-3's UG to become inaccurate. However, considering the objective is just to give students a model format to reference, and not factual accuracy, this may not be a problem in practice.

Also, this would disadvantage students doing AB-4. However, this disadvantage might discourage students from taking AB-4, which might be a good thing 😛

[damithc]

For screenshots of the GUI, do ensure that the steps to reproduce them are documented. Most importantly: the window dimensions for taking the screenshot. No MacOS please, no developer would want to buy an entire machine for AB. Preferably Windows 10. (With cost in mind, Linux would be the best choice, but I understand that Windows is more popular ;-) )

I wonder if this can be automated, using TestFx for example.

[fzdy1914]

I wonder if this can be automated, using TestFx for example.

Snapshot API of JavaFx can be considered.

[pyokagan]

@damithc

For screenshots of the GUI, do ensure that the steps to reproduce them are documented. Most importantly: the window dimensions for taking the screenshot. No MacOS please, no developer would want to buy an entire machine for AB. Preferably Windows 10. (With cost in mind, Linux would be the best choice, but I understand that Windows is more popular ;-) )

I wonder if this can be automated, using TestFx for example.

AB-3 doesn't have TestFX. Anyway, with the inherent flakiness of GUI testing, I don't think it would be worth the cost of implementation and maintenance.

I think we'll get 80% of the way there by just setting sane defaults (e.g. window sizes, split pane divider position) for the GUI, and then leaving them alone as much as possible when taking screenshots.

[j-lum]

I have moved the issue over to AB3.5 with a clearer problem statement and a summary of the discussions I had in person so that we have a digital record.