ReVanced / revanced-patches

🧩 Patches for ReVanced
https://revanced.app
GNU General Public License v3.0
2.43k stars 281 forks source link

docs: Add user docs #2618

Open Ushie opened 9 months ago

Ushie commented 9 months ago

Feature description

ReVanced Patches can provide documentation for the patches it includes, offering information on what they do, usage instructions (particularly useful for more complicated patches like third-party Reddit clients), and visual representations if applicable

Motivation

The community has long requested documentation or guides for ReVanced Patches, but currently, there's no official information beyond patch descriptions.

This lack of guidance makes it difficult for users to understand the necessary steps or actions.

Acknowledgements

oSumAtrIX commented 9 months ago

As of now the docs of the patches are present here. I am not quite sure if this is the correct place to even add them. Why would the documentation on how to write patches be in this repository, which is generated from the template? This would imply, that everyone that generated their patches from the template is also motivated to duplicate the docs. Instead, a better place for them would be our docs repository under the development section, whereas the patches themselves can document themselves for their specific purpose, this also aligns with the template as now, users of the template are also motivated to add documentation to their repository. Because the patches offer a public API though, they would have to be present here.

My primary problem of adding "user docs" is the intention of redirecting users to the repository in order to show them. Instead we would need a system that does not require the user to visit GitHub, a place meant for developers for development purposes and abuse the preview feature that is not intended for end users but developers. Some people have complained that they have to visit GitHub to read the ReVanced Manager docs and also had difficulties understanding how to navigate on GitHub.

With that being in mind, the docs folder could be structured into an API and a section for the users, the question here is, what exactly would be added to the user section?

With the docs comes also the constant cost of having to maintain it, when a patch is added, when a patch is changed and when a patch is removed. For that reason we would need to add a section to the contribution guidelines that explains outside contribution in this regard

oSumAtrIX commented 9 months ago

Your motivation also implies more for the expansion of the description for patches more than documentation on GitHub

LisoUseInAIKyrios commented 8 months ago

More complicated features such as external downloads and custom filters could really benefit from this.

It could be good enough to make an expansion of the existing description (or add a second larger description that is optional). Then it's embedded in the patches.json, and the website, Manager, or anywhere else can display that.

Basic support for html would be useful, so links to other sites (such as links to popular downloaders that work with the Downloads patch), ordered and unordered lists, and maybe images as well. To prevent arbitrary html to run in Manager (specifically if using forks of ReVanced template), Manager and the website should strip out all javascript and iframes (or use an inclusion approach of allowing only specific tags and remove all other tags).

oSumAtrIX commented 8 months ago

@LisoUseInAIKyrios The existing developer docs in this repo were moved to patcher. Now, there is space for "user docs" in this repository that can be made with markdown.

The problem with this is that when patches are added or removed, there's yet another consideration to take, which can be forgotten. This issue was also seen with the translation changes, where we now have to consider the string files whenever we add, remove, or change a patch.