(Consider) Adding Documentation containing overview and intended effects
Closed this issue · 2 comments
Hi. Good to see responsible developer practices being nudged through design choices and as modular components. It would be good to have a documentation (somewhere) that provides a brief overview of summary about the things included in this work, and the intended effects. A simple README.md type file would do as well. Minimally, I suggest following:
- What the main problem is that motivated this (link to your paper)
- What is this work, what does it provide (link to installation instructions or other technical documentations)
- What does this currently cover, e.g. list of integrations that are displayed in your screenshot with links to their relevant policies/docs, and a short summary of issues (if known)
- Contributions and collaborations - how should people help you with this in terms of highlighting issues, sharing their findings, contacting you, e.g. It could be directly emailing you, or opening a GitHub issue.
- (suggestion in connection with above) - What do you require help/assistance with, what would you like someone else to do / contribute for this? Is there something that needs testing, updated information, etc.
Other than these, it would be difficult for most people to comprehend what this work is actually doing, and what the result will be. A more descriptive hand-holding documentation might help get the idea across better, e.g. more images that show the current state, your code integration, updated flow screenshot, and a diagram outlining what has changed in terms of data/consent flows.
Regards, Harsh
Great, thanks for the feedback! This is really still highly in development. But completely agree that proper documentation is needed once this should shift towards production use.
I think, at this time, it's about demonstrating the feasibility that improvement to the status quo of privacy practices in apps could be much simpler than commonly thought.
And again, many thanks for the roadmap. That's incredibly helpful! I know you've got much more experience with building good documentation than me and will stick to your suggestions.
I've now vastly updated the README.md file to meet your suggestions!