Develop Research Page: Project Places - Documentation
Closed this issue · 9 comments
This issue is for coordinating around developing the resource page for Project Places Documentation.
The resource page lives in the following google document for easy editing, commenting, and revision:
https://docs.google.com/document/d/1OaKDksmuoi6nhaduZ4F96mTwQJvIFnfI8BqLx4MRO38/edit?usp=sharing
Once the page is in a decent shape, we will put a copy of it in the repository as a markdown file.
To work on this issue, feel free to leave a comment here and start editing the document. For questions, feedback requests, and other coordination tasks, please leave a comment here on the issue.
Please edit the google document directly and add your ideas to it. We can help with cleaning it up later.
@GeorgLink where do you feel this task is? (not clear from reading doc)
We completed a draft that we felt was good to be submitted, which is proposed in pr #251
The bottom of the document contained a note about the metric and why we developed it into what is now proposed to be added as a metric (I moved the note here and added more explanation):
This metric seemed to be too complex because it contained different aspects of documentation. During discussion we got hung up on discussing what elements to include or not. To resolve this issue, we did an exercise of differentiating types of documentation issues that we can then create metrics for. We chose one of those to focus on in the proposed metric and renamed the metric.
- Documentation
- Documentation Accessibility (this is what we developed the metric into)
- Documentation Accuracy
- Objectives
- (Relevance) Documentation is regularly updated
- (Relevance) Environment builds are up to date
- (FOSS standards) README & CONTRIBUTING files provide the intended information
- Objectives
- Documentation for Contributing
- (FOSS standards) README & CONTRIBUTING files provide the intended information
- Documentation in Source Code
- Documentation for Users
- Number of questions received each month that aren’t already answered in the FAQ (could point to the incompleteness of info provided or not updated on a regular basis), and reduction of this number over time
- Number of questions received each month that are already answered in the FAQ (could point to discoverability issues), and reduction of this number over time
- Documentation about Project Governance
- Code of Conduct
- Number of people using your project’s documentation (as measured by a tool)
@GeorgLink do you think that this is now being addressed as part of our current metric on Documentation:
https://chaoss.community/metric-documentation-usability/
As well as the development of new Documentation metrics at:
It is work in progress because we have two more Documentation metrics (Accessibility and Discoverable) in the work.
I think we should also consider Documentation Time Diversity.
TODO: create new issues for the metrics we have in work and close this issue.
Waiting for the creation of an issue for Documentation Time Diversity before we close this issue.
Split out as independent issues.