README: Should start with showing how to use project command line tools instead of API about ppci HOT 5 CLOSED

I made a ascii movie some time ago. I agree that this would be great to add to the readme. Maybe for now we can just show how to output assembly code. Agreed that the commandline tool has a more intuitive grasp of what the project can do.

The "movie":
https://asciinema.org/a/253109

from ppci.

I added command line usage as the first thing. @pfalcon can this issue be closed?

from ppci.

I added command line usage as the first thing. @pfalcon can this issue be closed?

That part looks great, thanks!

But... (I don't want to be nit-picky, especially given that you make these changes based on my reports. So, I hope we understand that it requires incremental elaboration to reach optimum, and such feedback is appreciated). While addition regarding command-line usage looks good, I'm no so sure about the change at the very beginning of the README. It's clearly based on our discussion in #21, but I didn't mean to put such a long list at the beginning of the README. IMHO, the beginning, how it was before, was approaching the ideal situation - the whole idea is to give quick but useful overview of the project in the first screenful of the README, to motivate people read further. Now it starts with 2 screenful of long boring list (no, it's interesting, but given that people don't even have enough of idea what PPCI is at that point, it's really boring).

Another issue is that given like that, the list is indeed too long, and too much vertical scrolling, while density of the info is low. Such a presentation of the list would be good for docs, but not for README. Long README == TL;DR.

So, specific proposals, assuming you're not 100% sure yourself that this is 100% improvement:

1. Put back a short list which was there before at the beginning of README.
2. Put this new section after the "Usage" section.
3. I'm well aware that it will duplicate some content at the very beginning of README (might be the reason why you do this change). That's why I actually suggest to brand (title) is as "Interoperability".
4. I'd suggest to condense the presentation of the list, doing it a-la #21 (comment) . (In no way I suggest to use the list there as-is, it's just an example, but IMHO gives an example of good visual density too).

And well, of course, that's just my IMHO, based on ideas described in #11 and other tickets. Please use your judgement to see what's better/how relevant something. I myself concerned with questions how boring nothing-original projects like https://github.com/DoctorWkt/acwj collect 3K stars in literally a couple of weeks, while interesting projects struggle to attract enough interest of the public, so in my opinion, anything which complicates perception of a project should be addressed.

from ppci.

The "movie":
https://asciinema.org/a/253109

Just to reply on this. Well, I'm not exactly fan of "learning by comics" ;-), so I'm biased on this. If the talk is about putting such a large by size recording into README, then I'm personally skeptical about it. But if to put scaled down screenshot, leading to this asciimovie, and into the appropriate section of the README (which to me looks "Documentation"), then definitely +1 from me - anything which caters for different groups of people (without "annoying" other groups) is a win.

from ppci.

Thanks for the updates in 6800995, looks good 👍 .

from ppci.