From 811718866f32cabd2c2ca3c7a9d78f693972e779 Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Thu, 20 Jun 2024 19:12:41 +0200 Subject: [PATCH] docs: Add docs for PgM, user support, and documenation --- CONTRIBUTING.md | 7 ++- docs/contributing/documentation.md | 50 +++++++++++++++++ docs/contributing/project-management.md | 71 +++++++++++++++++++++++++ docs/contributing/user-support.md | 27 ++++++++++ 4 files changed, 151 insertions(+), 4 deletions(-) create mode 100644 docs/contributing/documentation.md create mode 100644 docs/contributing/project-management.md create mode 100644 docs/contributing/user-support.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d66ca5d71..13c8894d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,9 +6,8 @@ Contributions generally fall in to one of several different categories, each of - [Translations](/docs/contributing/translate.md) - [Code](/docs/contributing/code.md) -- Documentation (details coming mid-September 2023) -- Project Management (details coming mid-September 2023) -- User support (details coming mid-September 2023) -- Social presence (details coming mid-September 2023) +- [Documentation](/docs/contributing/documentation.md) +- [Project Management](/docs/contributing/project-management.md) +- [User support and social presence](/docs/contributing/user-support.md) If you have any questions please join one of the [discussions](https://github.com/pachli/pachli-android/discussions) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md new file mode 100644 index 000000000..70b4e51bd --- /dev/null +++ b/docs/contributing/documentation.md @@ -0,0 +1,50 @@ +# Contributing to documentation + +> [!NOTE] +> These instructions are supposed to be complete and accurate. If anything is unclear or does not work please report it so it can be fixed. + +## Synopsis + +Thank you for wanting to improve Pachli by contributing documentation skills. + +After reading this document you will know: + +- Specific areas to focus on that would bring immediate benefit + +## Overview and activities + +### Writing contributor documentation + +[pachli-android/docs](https://github.com/pachli/pachli-android/tree/main/docs) contains the documentation for project contributors (you're reading some of it now). + +This changes slowly over time, but may be incomplete or out of date. + +These documents are generally either [How-to guides](https://diataxis.fr/how-to-guides/) or [explanations](https://diataxis.fr/explanation/). + +### Writing in-app documentation + +The app contains some "documentation", which will grow over time. + +Most of this is short messages, labels in the UI, brief descriptions of preference settings, and so on. + +However, some of it is longer text, and the amount of that will increase as the UI changes to show more hints on first-use to new users. + +### Writing website content + +https://pachli.app is the project's web presence. Its contents are a mix of: + +- [How-to guides](https://diataxis.fr/how-to-guides/), such as https://pachli.app/download/ +- [Explanations](https://diataxis.fr/explanation/), such as https://pachli.app/about/ +- Blog posts + - One for each release + - Others as necessary + +The website repository is https://github.com/pachli/website + +## Technology + +**Contributor documentation** is generally written in [GitHub flavoured Markdown](https://github.github.com/gfm/). + +**In-app documentation** is generally written as [Android resource strings](https://developer.android.com/guide/topics/resources/string-resource). E.g., see [app/src/main/res/values/strings.xml](https://github.com/pachli/pachli-android/blob/main/app/src/main/res/values/strings.xml). Familiarity with Android resource strings (e.g., how placeholders are written, how to manage strings with different plural forms) is beneficial, but not mandatory. + +**Website content** is managed using [Jekyll](https://jekyllrb.com/) and written in [GitHub flavoured Markdown](https://github.github.com/gfm/). diff --git a/docs/contributing/project-management.md b/docs/contributing/project-management.md new file mode 100644 index 000000000..3fd961987 --- /dev/null +++ b/docs/contributing/project-management.md @@ -0,0 +1,71 @@ +# Contributing to project management + +> [!NOTE] +> These instructions are supposed to be complete and accurate. If anything is unclear or does not work please report it so it can be fixed. + +## Synopsis + +Thank you for wanting to improve Pachli by contributing project management skills. + +After reading this document you will know: + +- Specific areas to focus on that would bring immediate benefit + +## Overview + +Project management is difficult at the best of times, and an open source project relying primarily on volunteer work is not the best of times. + +## Activities + +With that in mind the following list describes specific activities that are typically part of a project manager's role and would be useful ways to onboard on to the project before making a larger commitment. + +This is not an exhaustive list. If there are other ways that you would like to contribute and they are not listed here please start a [discussion](https://github.com/pachli/pachli-android/discussions). + +> [!NOTE] +> Each of the following has an implicit "... and describe your processes so other volunteers can help, and automate the work where possible" step. + +### Curating the list of open issues + +Left untended open bug reports and feature requests can grow without bounds. Activites to help include: + +- Follow up on incomplete bug reports to get more information from the reporter + - Device, server, relevant accounts, screnshots, etc +- Make sure that bug reports are not being ignored +- Identify and close duplicate reports +- Apply consistent bug report labels to make them easy to manage + +### Create new issues from user feedback + +- Create GitHub issues to track problems or feature requests reported by users to the @pachli account or the #pachli hashtag + +### Project prioritisation and planning + +As an open source project contributors are free to work on whichever issues they prefer. + +However, providing clear guidance about the relative priority of different issues can still be extremely helpful. Contributors may prefer to work on issues they know affect many people, or have a large impact on the affected users. + +Mining issue reports to extract common themes or frustrations, developing and proposing a prioritisation scheme, and using it within the project could be extremely helpful. + +### Follow up on open-but-stalled PRs + +A contributor might start a PR and then the work stalls. It is very helpful to identify stalled PRs, and help the work continue. + +- Had the submitter run out of time? + - Can someone else from the project finish the work? +- Did they not understand the review feedback? + - Can the reviewer update the feedback? +- Were they waiting for review and the project had not noticed? + - Determine who should review the PR, and ask them to assign it to themselves + +### Project internal communication + +- Communicate the state of ongoing activities to the rest of the project contributors +- Track requests for comments on proposal documents + +### Liaise between the project and other Fediverse projects + +The project needs to keep track of new features planned for release in upcoming versions of Mastodon to determine how and when to support those features. + +Keeping track of features in other Mastodon-like software is also important; both as they get feature parity with Mastodon, and where they have features Mastodon doesn't but we should consider supporting. + +The project often discovers bugs in implementation of those features (or documentation thereof), reporting and tracking those is also very helpful. diff --git a/docs/contributing/user-support.md b/docs/contributing/user-support.md new file mode 100644 index 000000000..5f735669c --- /dev/null +++ b/docs/contributing/user-support.md @@ -0,0 +1,27 @@ +# Contributing to user support and social presence + +> [!NOTE] +> These instructions are supposed to be complete and accurate. If anything is unclear or does not work please report it so it can be fixed. + +## Synopsis + +Users can post questions or problem reports to Mastodon, either mentioning the `@pachli@mastodon.social` account or using the `#pachli` hashtag. + +After reading this document you will know how to respond to these support requests. + +## Activities + +### Responding to questions + +- Answer the question. +- If you observe repeated instances of this question it may point to a UX issue in the app. Consider filing an issue to capture the possible improvement. + +### Responding to problem reports + +- Check the [list of closed issues](https://github.com/pachli/pachli-android/issues?q=is%3Aissue+is%3Aclosed) to see if the problem has already been fixed and will be in the next release. + - If it has then let the user know. + - If the fix is in a deployed version of Pachli Current then suggest they try that and confirm the fix works for them. +- Check the [list of open issues](https://github.com/pachli/pachli-android/issues?q=is%3Aopen+is%3Aissue) to see if the problem has already been reported + - If it has then let the user know (link to the issue), with a timeframe for the fix (if known) + - Ask if the user has any additional information that can be used to help resolve the issue, ask them to add it + - If it hasn't, ask the user to create an issue, or, if they can't do that, ask them for enough information so you can create the issue on their behalf