thwjason / fragments Goto Github PK

Hi @thwjason, since you invited me to provide feedback on your document, I thought it best to do it as an ISSUE in your repo. Overall, a good first approach. These are my suggestions:

1. Since this is the initial README for the repo, the first thing I would expect is a very description how to install the application, in the spirit of TL;DR.

2. I like the workflow table. It is probably best to use SCRUM terminology for the headings: Description -> Action, Whose Action -> Actor.

3. What you have called Automatic I would just call system or frontend / backend if confined to one of the latter.

4. I would phrase everything in the active voice, e.g. To apply, candidate has to fill in... -> To apply, the candidate fills in..., or Backend generates an email to be sent... -> Backend sends an email...

5. Your section 2, User Manual are actually the installation instructions. However I don't know enough about the project to assess whether these instructions are for development purposes only or also for production. I'm also not sure if a table is the most effective representation for installation instructions. Perhaps a multi-level bullet or numbered list is quicker to grasp.

6. You also need to find out how the application should be deployed, who the application custodian is, where credentials are kept etc. There is a separate HYF repo setup by Mauro called infrastructure. I'm not sure if it is visible to you, as it is a private repo, but perhaps you can refer to it or talk to Mauro to find out more.

7. I would rename your section *Construction Process to Project History.

8. For the admin stories I would not link to Aya's repo, as you/HYF have no control over this repo. Aya may decide to remove it at some point. Better to copy this stuff.