And that is why I suggested a single paragraph. An introductory summary. I have seen too many project pages that neglect this simple message: why is this even relevant. I believe those projects are easily ignored. I do not wish that to your effort.

I did notice the vast improvement on the website and the painstaking effort it must have taken. I also know that documentation is not exciting or glamorous to write. Yet I see that you recognize its importance. That is great. But, as you stated, your familiarity leaves you somewhat blinded to the experience of a new user and that is how I wanted to help: presenting feedback and questions that, hopefully, would lead to a better experience for future new users.

Oh, I know that. That was clear to me, but it may not be clear for other people. And I mentioned it for a few reasons:
- It does process game installers, like launchers and clients, so there is room there for some confusion. I mean, you do talk about the same things.
- Form here it flows that I believe to be some competition, in the sense that ./play.it and game managers are a bit mutually exclusive. I mean that I don't think game clientst usually handle native software packages and if you don the conversions then I don't expect you'll go back to the original installer. (I don't mean to say it never happens.)
- Game managers and launchers have a much easier time explaining what they do through the use of nice pictures. I think ./play.it needs something to hook possible new users. I mean, you have clearly done the hard part. (I think. I have yet to delve more into that).

It does not need to be comprehensive in the early page, just "this may be of interest to you if..." or "read on if you are troubled by this problem". For example, I appreciated the fresh way in which git-annex (git-annex.branchable.com) did this, with use-cases.
Please don't take this as a critique of your effort or work. I'm just simply providing a point of view in a genuine interest to help.


I did a short test with the game "140". This is how it went (some questions may be answered in the documentation and I have not reached it yet).
The GOG installer seems to be more recent than your package. The filename (and content) have changed. It was easy enough to update the name and hash of the file and it ran fine. It must be difficult to keep on top of this and I naively suppose most installer updates are minor and should not cause trouble. I wish I could pass the installer's name as an argument to force it through.
Speaking of arguments, I wonder if there are any. Maybe using environment variables to change some behavior, like setting some prefixes? A casual look at the code showed none, but I'll look for it in the documentation. I just wanted to dive right in.
In Arch Linux I noticed the result were two tar files. They were uncompressed, which I found curious. Still, when using ports I did find funny that the packages were compressed only to be immediately decompressed for installation, so that is not a problem. I can always compress them myself. But why two packages? One for code and one for assets. I can see that in games where the code is subject to frequent updates but the date is much more stable. But here, I'll have to regenerate both at every update, right?
These are the questions that were on my mind.

Taking another look at the documentation (I understand this is going long already), I wish there was a page explaining how it works from a high-level perspective. The game-specific pages are fairly repetitive and self-contained. That is good in that, if I care only about this one game, I get everything I need right there. I wonder if it is easy to ignore some information on purpose (after being an advanced user).
I do question your information grouping by step. In line with your "get all the info you need right in this page", if I use Arch, why would I care to compare my installation instructions with Debian? Why not group it by distro? "Are you using Gentoo? Do this: 1, 2, 3, 4. Oh, its Debian, then do this: 1, 2, 3, 4." Wouldn't this also make it easier to update the documentation once you add support for other distros?
Also, I noticed that you were quite careful in using the actual filenames in the instructions. Why didn't you do that for point 4, where you provide the installation command?

Oh, through the Alpha Centauri page I saw there can be command-line options. It is odd that I cannot find a shorter path to reach this page. Are some scripts (like the one for 140) still being updated to add support for these options?

This is already too long. I'll leave pointing out that in the Alpha Centauri's page you have "version sold sur GOG".