Improve documentation quality
SodaWithoutSparkles opened this issue · comments
[ ] Add detailed guide on how to get openjdk
winget install --id Azul.Zulu.17.JDK
For Adoptium/Temurin:
winget install --id EclipseAdoptium.Temurin.17.JDK
For Microsoft:
winget install --id Microsoft.OpenJDK.17
[ ] detailed how-to guide on how to re-log microG in another .md file to prevent it getting too long
Example
# no internet connection symptomes: offline, no internet caused by: change of password, etc. solution: re-login microG. Consult [wiki: re-log microG](link) for details.- Add wireframe as visual reference
image
Please edit & update the issue body & title instead of making a new comment
Add detailed guide on how to get openjdk
This is too off-topic for the scope of ReVanced, and it's documentation. The requirement is to have the SDK installed, how you do it, is not relevant to ReVanced.
Add detailed guide on how to get openjdk
This is too off-topic for the scope of ReVanced, and it's documentation. The requirement is to have the SDK installed, how you do it, is not relevant to ReVanced.
Ofc not at the main page. Create another resources section for downloading/installing. Or redir to other resources like the arch wiki.
At max a footer can be added to things like the requirements, that link to the places. For example the Java JDK requirement can have a footer to the Java JDK download page
At max a footer can be added to things like the requirements, that link to the places. For example the Java JDK requirement can have a footer to the Java JDK download page
That is a solution. But using winget is probably more efficient and harder to screw up. Thats the whole reason that I want a separate page. Linking them w/o providing any explanations is not the proper thing to do.
Sth like:
To get openjdk-17, you can choose one of the following varients:
- Zulu (recommended)
- Adoptium
- Microsoft
Zulu
To install the Zulu openjdk-17, visit their official site to download, or paste the following in a powershell window to run winget if you are on windows:
winget install --id Azul.Zulu.17.JDK
Visit the official website for detailed installation guide on Windows, debian-based Linux distros, or macOS.
Winget is microsoft windows specific. This guide is not
How about the edited one
E: Sorry for double comment, github mobile being github mobile sometimes.
Too complicated. Asking Java as a prerequisite and linking to where to get it is enough. Downloading and installing Java isn't a concern of this guide.
It would be helpful to have a visual reference for some UI patches. For example, when patching YouTube, I found it difficult to figure out what the Hide Info Cards patch referred to. Confusingly, there's a similar sounding Hide Info Panels option in layout options, but I'm unsure whether they're related. I remain unsure what UI elements I hide if I apply the patch and enable that option.
Having a visual reference would clear it right up. Some are obvious, but many are not.
Not sure if this is what you refer to by wireframe, apologies if my comment is redundant.
@aksel That seems like there should be a documentation for, but maybe in the patches repo. @oSumAtrIX your thoughts?
Descriptions can be used
Some of them are still quite cryptic, in my opinion.
Take for example hide-album-cards, which is described as "Hides the album cards below the artist description.". I can sorta guess my way around it, but it would be very helpful to just show a screenshot instead to remove any doubt.
Images are difficult to keep up to date, we would either need to embed them as resources or link to them and if we link them we need to think about where to upload them, how to keep them online and also consider leaking IPs to the uploading site
Images are difficult to keep up to date,
Just give a rough idea of what that is for is fine. For example, it does not matter what style the info card is, you will know that it is "the thing that pops up at upper-right" just by knowing any of the versions.
we would either need to embed them as resources or link to them and if we link them we need to think about where to upload them, how to keep them online and also consider leaking IPs to the uploading site
Just use GitHub as the image CDN. When you push changes to github it would be updated.
I don't know if abusing GitHub as an image CDN is allowed
How else do they expect you to make github pages? Anyway, I saw people using discord CDN and oracle free tier VPS too.
Or maybe imgur is also an option.
GitHub may be using different CDN for pages.
Imgur is a third party, to which the questions that I mentioned earlier above apply.
No, I mean github pages generated with the repo's readme. When you want to include images in the readme, most likely you would upload the images to github and fetch the raw image link. When you upload an image to github issues, it also uses the github domain, as shown below:
Source: xkcd 2192
As the patch descriptions should be in the patches repo, the images could live in the same repo as the descriptions. Or they could live in a repo called sth like revanced-resources as the images are raw binary files.
The images are supposed to be served on the respective GitHub page, and not abused as a general purpose CDN outside of GitHub
So the solution is to make a .md file in the revanced-patches repo and create the description in said .md file, therefore satisfying the requirement. If you want this to be served somewhere else just link the .md file. This also adheres to the rule of "documentations should be placed in the relevant repos".
If the situation somehow changed and we need to move away from github entirely, we could either serve the files and images from revanced owned server behind cloudflare cache (sth like static.revanced.app), or serve the .md files with the repo (with alt-text of images) and images via other CDN services which we will find later.
The binary images file might be stored in another repo as binary files are handled poorly by the git protocol and will cause the repo size skyrocket.
Also, isn't linking from the source instead of downloading & re-uploading the "better" way of doing things on the internet as it sorta gave some attribution?
The images wouldn't be able to be showed on ReVanced Manager for example if it were only in Markdown files. Additionally images have to be uploaded regardless so the issue doesn't change
The images wouldn't be able to be showed on ReVanced Manager for example if it were only in Markdown files.
Maybe launch a android webview instance?
Additionally images have to be uploaded regardless so the issue doesn't change
To github.
At this point anything is better than nothing unless it is blatantly wrong and totally misleading.
Maybe launch a android webview instance?
Highly unpractical. The image should be shown under each respective patch.
To github.
As explained earlier:
Highly unpractical. The image should be shown under each respective patch.
That would be even more unpractical as it would take up too much space. How about a info button next to the patch?
Clicking the info button would link to the respective entry.
Edit: If you want the image to be in manager why dont embed it within manager?
Maybe we should clarify, where should the description be stored? I was thinking that there should only be a single source of the instance which is the single file in the patches repo.
That would be even more unpractical as it would take up too much space.
No, it would be highly practical as it can be displayed without loading GitHub via a web view.
How about an info button next to the patch?
The image can be shown below; it doesn't matter; the initial problem exists in the end in the end.
Edit: If you want the image to be in manager why dont embed it within manager?
Because ReVanced Manager is patch agnostic.
where should the description be stored
The description is already stored as an annotation for each patch.
After a lengthy discussion in discord, the final conclusion is to
- Embed metadata descriptions and inages in the patches
- Generate a
.mdfile from information in 1 for cli users, link them to cli @Metadata(description="", images=[""])
- Markdown files aren't meant to be consumed by ReVanced CLI.
Link them from github repo or revanced.app
Not really a clean solution as the image would be present as a resource file for the patch and as an asset in the repository
How else? Launch GUI viewer? Use sth like jp2a to convert?
Better than nothing at least.
The CLI can not show images. It will simply not be available. At max it can dump the image file
Yeah, maybe dump the image file in cache and prompt the user to view it when they list patches
Currently, we lack the ability to create proposed wireframes; for that reason, this issue is stale; in case you have no solution to this, the issue will be closed due to being out of our scope.