Improve README.md

[eyecatchup]

Hi Peter,

I reviewed my older open source commitments and therefore stumbled upon your GitHub repository again.

First of, compliments for keeping APK Downloader uptodate! :+1:

Now, I noticed that you still use the icon that I created for my version. Which is perfectly fine, but just the credit for it was missing. So I wanted to update the README. Then I noticed that you seem to have missed my repository (Yep, there was already a public git repositry before ;)). So while I was on it, I also updated and reformatted some other parts.

If you're fine with the changes, I'd appreciate it if you'll merge this change. Otherwise, please let me know what's wrong with it. Thanks in advance! :)

Cheers!

[Rob--W]

Credits where due, of course.

Much of your proposed README can be said with fewer words, while removing relevant information from the credits (i.e. who is responsible for what?). Could you revert your changes and only edit the parts that need to be changed?

The prominent reference to your old Github repo seems not super important, because Peter's code is really based on the zip file. You can edit the credits to something like

Many thanks to [redphoenix89](http://codekiem.com/) for the original version, and Stephan Schmitz (aka [Bexton](http://forum.xda-developers.com/member.php?u=4273402)) for the improved version and the [new icon artwork](https://github.com/eyecatchup/android-play-store-apk-downloader-crx/commit/c3985ac757dcb6c10bf053590401f824490e96a5).

Did I miss anything else of importance?

[eyecatchup]

Hey Rob, thanks for your comment. With all respect, I think you may wanna read the initial change again!? Seriously, again, saying it with all respect. But..

You said I removed relevant parts of the credits section. WTF!? Should we list all my changes and all changes by redphoenix89 as well? Did I even asked for that? No. And it is not the correct place for it anyway! A name, a brief description of responsibility and a link [to the details], that's all what should go in the Author / Credit section. Speaking for the credits section, from my point of view my proposed change reflected much better the defacto contribution all four of us invested in this project (not saying it was perfect; that's why I changed it again (again, not saying it's perfect now)).

As for the "prominent reference" to my old Github repo: Yep, you're absolutely right. It is not super important. However, saying that "This project was started because [snip] I (Lekensteyn) prefer a public git repository [snip] instead of some obscure zip package from a random forum." sounds like if I would have shared some obscure artifact in the dark corners of the internet and finally Peter came and brought it into the light of open source. (exaggerating!) And saying "Prior to version 1.4.1, only a source distribution was available [..]" is just wrong. Last but not least, I disagree with the term prominent. In fact, if you compare and take a close look at the sections, you'll see that I just split 2 paragraphs into three - one for each version. I thought it would make more sense. And if prominence was added, than for all.

Long story short: You were right about another point: "Much [..] can be said with fewer words." With this in mind and given the fact that pretty much of this section was actually not so super important at all, I think I came up with a quite good idea for this section now.

Oh, but what I did kept is the description. Because I think that is super important.

I hope you don't get me wrong now [because me trying to be kind of sarcastic] and see a bit more of my point of view. As you said; Credits where due. Without redphoenix89 we probably wouldn't have it at all and he worked several months on the initial version to pull it off. I spent several weeks on deobfuscating, debugging, reading docs, fixing, rewriting, supporting on XDA & more. And Peter and you spent probably another several weeks during the last 2 years for.. well you know it.

In the end, the latest proposed version reflects it in the best way I can think of. And in a fair one. Thoughts?

[Rob--W]

You said I removed relevant parts of the credits section. WTF!? Should we list all my changes and all changes by redphoenix89 as well? Did I even asked for that? No. And it is not the correct place for it anyway! [...] Speaking for the credits section, from my point of view my proposed change reflected much better the defacto contribution all four of us invested in this project (...)

Considering that there are multiple forks, we believed that it is in the interest of the users to know exactly which changes we made in order to make an informed decision about whether to use one over the other. "Improved" is vague and doesn't tell the user a thing.

At the first sight, your new README looks good in terms of readability, but there is also information missing. Peter mentioned the reason for forking the zip file and hosting a crx file, it must still be there.

I'll leave it up to Peter for further review for now.

PS. If you want to edit the README again, use https for my website instead of http.

[Lekensteyn]

Hey @eyecatchup, first I must thank you for the work you did on the 1.3.x series, the artwork looks great. Support is also something not to underestimated, so kudos for that :+1:

About these changes, I did not know that the artwork was yours and will of course give credit for that. imo the addition of a summary for the functionality (+ some marketing) at the beginning is OK, but please keep the history intact (especially to prevent someone from adding more privacy-evading shit like GA).

I honestly did not know that you had a repo since it was not advertised on that forum topic. A single-time source drop is not really in spirit of FLOSS either. A file from a random forum does not really encourage collaboration and makes it difficult to track changes, a git repo is the perfect method to solve those issues. Hence my statement about an "obscure file from a random forum".

Now about the authors/credits section, "improved/rewrite" is not really meaningful. What was wrong with the previous section, besides not linking to your GH account and artwork?

Somehow you dropped the website referring to the PHP version, is that intended?

I like Robs short addition, would that be OK for you?

[eyecatchup]

Considering that there are multiple forks, we believed that it is in the interest of the users to know exactly which changes we made in order to make an informed decision about whether to use one over the other.

I see the point. However, as I said, I believe it is the wrong section for this info in general. Sure, the user should know what changes are included in which version. But, again, these specific changes should not be listed in the author/credit list/section of any repositpory's main README. Instead, these specific changes should be listed/explained in (great) detail on the changelog or the faq or whatever page. This would not only be more professional, but also far more maintainable for you and useful for users. My 2 cents.

"Improved" is vague and doesn't tell the user a thing.

Absolutely correct. Streamlined the section once again in 69f3210.

Also, I flipped the ordering for the list of authors. More common to have the latest on top; which also gives you a more prominent place. :P

You may say that it's now even more meaningless. But, again, there shouldn't be any details anyway.

BTW, if you think there's something that is a crucial different to another package, I'd put it at the top, giving it an extra section! That would be helpful for the user.

---

About these changes, I did not know that the artwork was yours

That was my guess too. I never assumed bad intentions.

and will of course give credit for that.

Well, again, that was my guess too. ;-)

imo the addition of a summary for the functionality (+ some marketing) at the beginning is OK,

Well, a summary is probably the very first thing in 95% in main README files for open source software distributions. It is a relevant part of information for users.

but please keep the history intact

Which exactly? This:

This original version of this Chromium extension can be found on http://codekiem.com/2012/02/24/apk-downloader/. Improvements have been made by Bexton.

This version is based on apkdownloader-1.3.4.zip as found on http://forum.xda- developers.com/showthread.php?t=1809458. This project was started because the 1.3.4 version became broken with Chromium 23 and because I (Lekensteyn) prefer a public git repository to work on code instead of some obscure zip package from a random forum.

or this:

Prior to version 1.4.1, only a source distribution was available, but since I found out that some third parties provide a CRX file with spyware, I decided to make a CRX available as well.

(especially to prevent someone from adding more privacy-evading shit like GA).

Sorry, I really can't get your point here. How could anything prevent that at all!? No way at all!

First, if you really think that it is a crucial info for the users, you should also note that v1.0 - v1.2.1 used GA aas well as obfuscated code and redirected to codekiem.com on every download.

Second, saying "some third parties provide a CRX file with spyware" is vague too. Even worse. It leaves out the most important info: which parties!? You must either list specific names or must not mention it at all. But this way, it just frightens the reader and leaves uncertainty. For this, the last option is the one I would prefer: A general note like:

Note that several cloned versions of APK Downloader floating around some were found containing potentially unwanted code additions (tracking scripts, affiliate redirects etc.). In order to prevent being spoofed, take care to download only from the sources listed below:

• list.. bla bla.. link

I honestly did not know that you had a repo since it was not advertised on that forum topic. A single-time source drop is not really in spirit of FLOSS either. A file from a random forum does not really encourage collaboration and makes it difficult to track changes, a git repo is the perfect method to solve those issues. Hence my statement about an "obscure file from a random forum".

That true. Got your point. Nonetheless, I think the whole section should be removed. Or, as a second paragraph of the summary section, add something like:

Up to version 1.3.4, only a source distribution was publicly available. So this repository was created in order to have a single public place to work on the APK Downloader code.

Now about the authors/credits section, "improved/rewrite" is not really meaningful.

See my answer/comment on this above. Agree. Changed.

What was wrong with the previous section, besides not linking to your GH account and artwork?

Well, I said it before. Yeah, you list changes that you did while, at the same time, don't list ours. But that is not even what I "complain" about. Even if I could, considering that I also rewrote the [initial] download code. And I also cleaned the extension. And so on. Anyway. Of course I appreciate all your changes. And sure, credit where it's due. But, again, you clearly chose the wrong section, IMHO (as I tried to explain multiple times now).

And, seriously, you don't prefer the right side here: http://view.xscreenshot.com/9e7114826e4398e2e7a49435996dfb5b ?

Somehow you dropped the website referring to the PHP version, is that intended?

This code is dead. The author put a note on the top of that post saying it is obsolete since long ago and he just left it for "historical" reasons. Linking to an obsolete, unmaintained code is useless, IMHO.

---

Phew, I think I'm done for now :D

Again, don't want to claim any of your reputation. Just want it to be equally fair. On top, a clean, "standardized" README would be nice to have. But that is, of course, your decision in the end.

[eyecatchup]

PS. If you want to edit the README again, use https for my website instead of http.

@Rob--W Done in bcc78e

[Lekensteyn]

The historic refer to the origin of sources (to give codekiem extra credits as he is the original author) and the reason why this project/fork started.

I'll get back to this later (probably next week), need to finish some other work first ;-)

[eyecatchup]

@Lekensteyn Sure, take your time!

A final suggestion though: https://gist.github.com/eyecatchup/f803f8e8ba9058ea62a9

IMHO, the best version so far. I tried to keep texts as short as possible while trying to including all the relevant "historical" and other information that Rob / you mentioned. The only thing that would need to be changed, from my POV, is the brief list of your updates here https://gist.github.com/eyecatchup/f803f8e8ba9058ea62a9#version--140

A quick feedback whether this fits better what you have in mind would be appreciated but is not super important neither. ;-)

[Rob--W]

@eyecatchup That gist looks much better than your current version. Could you amend your commit?

With the following changes:

• Unblockquote the Download & Installation section.
• Remove the bold face from "APK Downloader" all over the place (and maybe also the italics).
• Version history: Fix the link at the first bullet point. [link name] (aka ...) is interpreted as a link-to-aka with link text "link name", certainly not what you intended to write. To fix the formatting while still using the link id, use e.g. [description of link][link id].
• Version history: Fix the grammar in the third bullet point ("...repository off of ...").
• Version history, third bullet point: Although true, the last sentence ("official") is pretentious. Replace the sentence with "This is now the actively maintained version of APK Downloader".
• Credits: Omit the titles of the "roles".
• Use sentence case, not title case for the headings.
• Other projects: PHP script. Might be worth keeping for historical purposes.

Even though I find the gist much better than the current PR, I've not decided yet whether it is an absolute improvement over the current README. (and out of all main authors, your role gets the most words in the README. This is natural, since it's easier to recall your own achievements than others.)

[eyecatchup]

Done:

• Unblockquote the Download & Installation section.
• Remove the bold face from "APK Downloader" all over the place (and maybe also the italics).
• Version history: Fix the link at the first bullet point. [link name](aka ...) ...
• Version history: Fix the grammar in the third bullet point ("...repository off of ...").
• Credits: Omit the titles of the "roles".
• Use sentence case, not title case for the headings.
• Other projects: PHP script. Might be worth keeping for historical purposes.

As for the last point from your list:

• Version history, third bullet point: Although true, the last sentence ("official") is pretentious. Replace the sentence with "This is now the actively maintained version of APK Downloader".

The sentence you refer to was kind of a placeholder and was meant to be changed anyway. That what I meant when I said

The only thing that would need to be changed, from my POV, is the brief list of your updates

and out of all main authors, your role gets the most words in the README. This is natural, since it's easier to recall your own achievements than others.

Again, your achievments were subject to change in my drafts anyway. As you said, I recall best what I did. You recall best what you did. And so on.

I replaced the sentence in question with [XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX]. Except for this line, which you should replace with the brief summary of your changes.. You're fine with the rest now? https://gist.github.com/eyecatchup/f803f8e8ba9058ea62a9

EDIT PS: "off of" is gramatically correct, btw. :P

[Walkman100]

EDIT PS: "off of" is gramatically correct, btw. :P

Agreed, but there are two ms in grammatically :stuck_out_tongue:

[eyecatchup]

EDIT PS: "off of" is gramatically correct, btw. :P

Agreed, but there are two ms in grammatically

@Walkman100 Agreed. However, that wasn't a grammatical error but rather a typo, which, by definition, are accidental. Correcting typos, especially online, is like explaining to someone they have an elephant sitting on their head - pretty pointless. They probably realize the elephant is there and, if they don't, they'll probably catch it later on and feel silly about it. ;-)

[Walkman100]

I work on repos in an organisation with a friend, and he is absolutely terrible at spelling, since I have admin rights on the organisation I can edit his comments - which I do, after calling him out with IM. That's one of the things I love about GitHub - you can edit comments any time after you submit them, any amount of times. Also I was joking, since you were correcting someone who was correcting you, so I was... yeah, not going to try type that out.

Anyway, Glad to see we are getting somewhere on this XD I think you should push your changes on the Gist to this PR, makes it a bit easier to find changes. If you don't want a commit you can always remove it anyway.