Repository navigation
Conversation
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is still a work in progress. However, I now got most of the major changes done, and since I might still take a while for the rest and am a bit afraid that someone else might want to start doing the same, I decided to open the current state as a draft pull request.
When I started looking into how to deploy AppImages a few weeks ago, I had big troubles understanding the documentation:
There was very much duplicated information which made it hard to find a specific detail that was only mentioned in one of the duplicated parts and generally to read through the documentation.
There was very much outdated information, from commonly recommending the deprecated linuxdeployqt tool, to the deprecated AppRun.c file, not even mentioning the new go-appimagetool, many invalid and outdated links, old Linux versions (one even being eleven years (!) old), etc.
The same terms were sometimes used for very different concepts, e.g. "manual packaging" for
which obviously led to much confusion.
There was much conflicting information, mostly due to duplicated information, which has been outdated in some parts and updated in others, or the same terms used for different concepts.
There was missing information that was expected in other places, e.g. which resolutions are valid for icon files.
There was information scattered across places or in the wrong places, e.g. several pages contained some details about desktop files, but no page in the packaging guide clearly explained everything related to it and how to create them.
There were weird structure decisions, e.g. placing a software overview, mostly about low-level software that the average user should not use, in the introduction section instead of the reference section.
There was no single detailed comparison about the differences between the individual tools and approaches to create an AppImage, resulting in a lot of confusion which one(s) to use and how to create AppImages.
Some things were just explained badly, e.g. the pages about using make to create an AppDir lacked the most important information on how to do so, and the linuxdeploy page made it very hard to understand how to use it without make.
I think much of this is not that noticeable when you know your way around AppImages well enough. Sure, you might notice many things aren't up to date and that some things are duplicated, but I think you can generally read through it, understand what's meant, fill in the missing information and don't really realize how hard it is to understand all of that if you don't have that prior experience and knowledge.
I also think that much of this comes from the fact that the AppImage ecosystem has evolved a lot in the past years. There are many things that have considerably improved, e.g. going from having to package the entire AppDir by yourself and use appimagetool directly, over tools like linuxdeployqt that package all shared libraries from an existing AppDir structure, to linuxdeploy, which can get all necessary data with command line arguments and requires no pre-existing structure.
I also noticed that some old parts were expecting the reader to repackage existing packages, probably out of a time where AppImages haven't been commonly used, while other parts were mainly directed to the application authors.
I can imagine that the focus was on developing better solutions and improving the AppImage packager and user experience. And it's understandable that, with many parts duplicated, you don't always find the time to really go through the documentation and update everything correctly when something changes, slowly leading to a worse documentation state.
All of this is to say, I hope that you don't take this as an insult. I do appreciate the work you put into AppImages and the whole ecosystem and I understand that the focus has been on other things, but I do think that the documentation is in a bad state.
And this also led to frustration by other users. See for example https://discourse.appimage.org/t/does-appimage-include-all-shared-library-dependencies-by-default/509/6, where someone is frustrated with the documentation as they don't find a guide on how to automatically package shared libraries, or ruffle-rs/ruffle#12401, where someone didn't even know about the other available tools that help with this, which is the core thing the documentation should explain in my opinion.
Therefore I started to rewrite, improve, update and correct the documentation.
I started with the linuxdeploy page, which I had personally had a lot of struggle with to understand previously. From there on, I worked my way through the documentation (mostly the packaging guide), and went on to improve the structure, add a comparison of creation tools & approaches, deliver better explanations, update the outdated information and add additional information.
Here is an overview of my changes:
New sections that contain collected information
Other sections that have been rewritten
Updated & improved sections
Split up sections
Minor improvements
For more details, each commit contains an in-depth message of all changes I have made within it.
Also, this pull request documents the features introduced in linuxdeploy/linuxdeploy#288, so it depends on that being merged.
As I said in the beginning, this is currently a work in progress. I still have a lot of todos and there are quite some sections I haven't really gone through yet at all.
But I still thought that now is a good time to create this draft PR, as most of the major restructuring is done and it's easy to see my desired end result. I'll probably still take a while to finish this (especially as I basically worked the entire last week from waking up until going to bed on this, and will continue slower as it's now known that I'm working on it).
Edit: This is just the motivation and description of the first 13 commits; see my other posts for the description of the rest.
#102 (comment) is an overview over the issues this pull request fixes, but I have to write this in the first post for GitHub to recognize it:
Fixes #9, fixes #28, fixes #29, fixes #30, fixes #32, fixes #34, fixes #35, fixes #57, fixes #66, fixes #68, fixes #73, fixes #77, fixes #84, fixes #87, fixes #88, fixes #98, fixes #99.