Skip to content

Commit

Permalink
docs: finish story mockups
Browse files Browse the repository at this point in the history
  • Loading branch information
kevinAuberson committed Aug 25, 2024
1 parent 7cb4283 commit 876d4a5
Show file tree
Hide file tree
Showing 3 changed files with 66 additions and 15 deletions.
Binary file removed docs/src/img/png/error-cmd-compile.png
Binary file not shown.
Binary file removed docs/src/img/png/example-exo.png
Binary file not shown.
81 changes: 66 additions & 15 deletions docs/src/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ todo: document other OS

## Mockups
## Case study with the classic experience
Let's consider a typical exercise:
Let's consider a typical coding exercise that David need to do:
#### Dog message
Write a small program that displays this message built with the first 2 args. You don't need to check the second arg to be a number.

Expand All @@ -30,7 +30,7 @@ The dog is Joe and has 4 legs
<details>
<summary>Solution</summary>

```
```c
#include <stdio.h>

int main(int argc, char **argv) {
Expand All @@ -44,25 +44,76 @@ int main(int argc, char **argv) {
</details>
---
To solve this exercise, we first read the instruction, then open an IDE, manually create a `main.c` file, copy-paste the starter code, read the existing code, and complete the parts that need to be developed. Once we believe the code is ready, we compile it by opening a terminal in the IDE and typing `gcc dog main.c` — oops! it should have been `gcc -o dog main.c`
![compile error](img/png/error-cmd-compile.png)
To solve this exercise, David first read the instruction, then open his IDE, manually create a `main.c` file, copy-paste the starter code, read the existing code, and complete the parts that need to be developed. Once he believes the code is ready, David compiles it by opening a terminal in the IDE and typing `gcc dog main.c` — oops! it should have been `gcc -o dog main.c`
```bash
PS C:\Users\david\CLionProjects\dog> gcc dog main.c
c:/program files/mingw64/bin/../lib/gcc/x86_64-w64-mingw32/12.2.0/../../../../x86_64-w64-mingw32/bin/ld.exe: cannot find dog: No such file or directory
collect2.exe: error: ld returned 1 exit status
PS C:\Users\david\CLionProjects\dog> gcc -o dog main.c
PS C:\Users\david\CLionProjects\dog> ./dog Joe 4
The dog is Joe and has legs
After this, we input the name and number of legs, and compare the output manually to see if it matches the expected result. Opening the instruction again, we realize that the number of legs has not displayed ! We go back to the code, add the age variable, recompile, and run the program again, entering the name and number of legs once more. This time, is the output correct? Now we check our code against the solution... Okay, we could have used `printf` instead of `puts()` twice to display the full name. Moving on to the next exercise, we search for the instruction, and the cycle repeats...
```

After this, David input the name and number of legs, and compare the output manually to see if it matches the expected result. Opening the instruction again, he realizes that the number of legs has not displayed ! He goes back to the code, add the age variable, recompiles, and runs the program again, entering the name and number of legs once more. This time, is the output correct? Now David checks his code against the solution... Okay, he could have used `printf` instead of `puts()` twice to display the full name. Moving on to the next exercise, he search for the instruction, and the cycle repeats...

All these additional steps around writing the code may seem insignificant at first glance, but their accumulation results in considerable friction. Additionally, there will be very few manual executions, meaning limited opportunities to gauge progress and adjust the code accordingly, coupled with the mental burden of compiling and running the program manually.

![classic-xp.opti.svg](img/svg/classic-xp.opti.svg)

## Case study with the PLX experience
### Home page
For running PLX, the user need to run `plx` in the correct folder that contains the exercises if there is not ".plxproject" file in the given top-level folder the app provides a warning messages.

Let's consider a struct exercise that Alice need to do:

#### 2. Basic dog struct

Write a basic dog structure with a name and legs number. Print given dog with first 2 args. If `-n` ask to define a new dog, and if `-s` show the size of the struct.

<details>
<summary>Solution</summary>

```c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

typedef struct {
const char *firstname;
short legs_number;
} Dog;

void printDog(Dog *dog) {
printf("The dog is %s and has %d legs\n", dog->firstname, dog->legs_number);
}

int main(int argc, char *argv[]) {

if (strcmp(argv[1], "-n") == 0) {
printf("New dog\nName: ");
printf("\nNumber of legs: ");
Dog newDog = {.firstname = argv[2], .legs_number = atoi(argv[3])};
printDog(&newDog);
} else if (strcmp(argv[1], "-s") == 0) {
printf("sizeof(Dog): %lu\n", sizeof(Dog));
} else {
Dog dog = {.firstname = argv[1], .legs_number = atoi(argv[2])};
printDog(&dog);
}
}
```
</details>
---
For running PLX, Alice needs to run `plx` in the correct folder that contains the exercises if there is not ".plxproject" file in the given top-level folder the app provides a warning messages.
<!--TODO: Think about the subfolder opening issue. The app will ask again for a folder.-->
![home.opti.svg](img/svg/home.opti.svg)
Arrows on the picture illustrate the event. This is the home layout of the app PLX. There are three options on this page. First, press `r` to access the last exercise that still needs to be finished. When PLX starts an exercise, it will automatically open the IDE with the correct file and compile the file for the first time. Secondly, press `l` to access the listing of exercises, and lastly press `?` to show the command of the app.

### List page
Arrows on the picture illustrate the event. This is the home layout of the app PLX. There are three options on this page. First, press `r` to access the last exercise that still needs to be finished. When PLX starts an exercise, it will automatically open the IDE with the correct file and compile the file for the first time. Secondly, press `l` to access the listing of exercises, and lastly press `?` to show the command of the app. So, Alice use PLX for the first times then she press `l` and enter in the list view.
![list-1.opti.svg](img/svg/list-1.opti.svg)
Expand All @@ -79,20 +130,20 @@ The meaning of colours for exercises: green = done, orange = one test pass, and
Press `Enter` to go to the exercise preview and `Esc` to go back to the exercise list. The preview exercise shows the instruction and the path of the main file, but doesn't run any build in background to save resources. The preview is not another page, therefor the `j` and `k` shortcuts will continue to work and the preview will be adapted.
### Exercise page
![exo-1.opti.svg](img/svg/exo-1.opti.svg)
The checks are red when they are not fail and green otherwise. The first failing check is automatically opened. To navigate and see details of the next checks use `Ctrl+d` down and `Ctrl+u` up. When the user saves the exercise file on the IDE, PLX will automatically run compilation and checks, and update the results of the checks.
Alice found the exercise she needs to do. Her IDE opened the C file corresponding to the exercise.
The checks are red when they are not fail and green otherwise. The first failing check is automatically opened. To navigate and see details of the next checks use `Ctrl+d` down and `Ctrl+u` up. When Alice saves the exercise file on the IDE, PLX will automatically run compilation and checks, and update the results of the checks.
![exo-2.opti.svg](img/svg/exo-2.opti.svg)
When all checks are green the exo is done, the user has the options to press `s` to see the solution. Scrolling inside the solution is with `k` (up) and `j` (down).
When all checks are green the exo is done, Alice has the options to press `s` to see the solution. Scrolling inside the solution is with `k` (up) and `j` (down).
![error.opti.svg](img/svg/error.opti.svg)
This is an example of report error of compilation if the user save the file and there is a issue to compile the code.

This is an example of report error of compilation if Alice save the file and there is a issue to compile the code.
![plx-xp.opti.svg](img/svg/plx-xp.opti.svg)
## Landing page
todo
Expand Down

0 comments on commit 876d4a5

Please sign in to comment.