Meaningful package descriptions!


hmc

Active Member
Joined
Dec 19, 2011
Messages
787
Location
Bavaria, Germany
Hi guys,


there is something about the Repo (as well as the App store and openhandhelds archive), which really annoys me:


The package description often does not describe the package contents in a manner that if the potential user reads it, he really knows what's in it.


E.g. today I saw there is an update for package "FBA with CAPEX FE". "Okay" I thought, no idea what this is, so click on it and see what the description says. ... "Port of GP2X/CANOO FBA with CAPEX Front End".


At least I know what GP2X and CANOO are...


The category suggests that it's an emulator. But it seems I need to ask google in order to learn what this is.


There are many packages like that.


Friends, please, PLEASE, if you release a software package, take the additional minute to write a meaningful description!


Thank you!


Daniel
 
a simple link to thread about release would be much better, but this is something milkshake should include in the repo, and the pxlm would have to be adjusted to it
 
I don't think there'd be a need for any change. PXML supports descriptions, that's where these are getting pulled from. We just need to be a little more... verbose. Not everyone knows what the heck we're talking about.
 
A link to a corresponding forum thread would be good in addition, but not as a substitute for a good short description.


The description can be displayed in an on-Pandora PND installation tool, such as PNDstore.


A link instead of a good description would require the user to follow that link, read through the thread until he finds out what it's all about, and this can consume - depending on the individual thread - a lot of time. PLUS following the link is not always convenient, e.g. if you just like to skim through a few newly uploaded apps...


Daniel
 
What about the comment field on the repo? I think it's a good place for improvement suggestions in regard to the publication of the app itself.


One advice to hmc - that is not the ususal way selecting software, compare it to some linux repos with 50.000+ packages. It will eat your time if you check out all of them in search for useful software. Get your focus on the things you want to achieve and search for software forged for that. Doing this the software you don't know is the software you don't need.
 
I agree completely with hmc. Now, for some things it might not be quite finalized yet - FBA is still kinda beta, isn't it? - but I would really like a good description in the PXML for most things. Perhaps another area for those of us who don't code very well? Writing descriptions?


And what do you mean by "This is not the normal way"? It is not like we're being deluded with hundreds of apps every day - I definitely check out all new releases when they pop up the sidebar.
 
Maybe i've seen to many apps already. And i'm still waiting for my pandora, so my todo list is growing with every new release. I realized that there is more multimedia content in the world than i could ever consume in my entire life. I understand "check out" in a term of testing the app itself, if i'm wrong with that and you had "read the description to check it is useful" in your mind then i do agree with you completely. :)


Writing descriptions not discussion, it's an activ development or editorially work. The wiki is designed for that type of community project and due to that a better place for forging better descriptions.


My humble opinion in this case is using the simplest and direct way. There is a report button on the repo. You can email the publisher directly and suggest improvement of the description. If you already find out what it is like hmc did you could throw in your description proposal and i think any dev would like your contribution.
 
This wins the prize for worst description ever: http://repo.openpand...rheels-1.0-6540


But as double7 suggests, we need solutions not problems. Most of us have already encountered the terrible descriptions, let's get a plan of action together to change them!


For example, a much better description could be distilled from here: http://www.headoverh...rupal/en/node/2


I'd write it right now if I didn't have to go out! Bug bags this one, I'll do it later.


If you want to help, pick a package, learn about it, write. I'd be willing to proof read, and we can send new descriptions to the maintainers and fix this problem!


Edit: Without further ado:

A remake of the crticically acclaimed ZX Spectrum isometric puzzle game Head Over Heels,
where you control two characters with distinct abilities.


Head can jump high, control himself in the air and fire doughnuts to paralyse enemies.


Heels can run fast, climb stairs that Head can't, and carry objects around the room.


Together they must escape from Castle Blacktooth, liberate four opressed planets and defeat the Emperor.
 
Last edited by a moderator:
I'm all for that. I'll be on it tomorrow (this afternoon, we have a birthday party with 18 kids, so I'll have to have some time to recuperate).
 
If someone can point me to some stuff that needs better descriptions, I'd be happy to write a few. I can't guarantee I'd be able to write too many, or make a regular thing of it, but every little helps, I hope!
 
Last edited by a moderator:
A list of Apps which could use better descriptions:


Chaos Strikes Back: http://repo.openpand...=detail&app=csb
Is this ok?



Code:
Chaos Strikes Back is a 3D real-time action-RPG for the Pandora, converted from the Atari ST game of the same name.


It is the follow-up/expansion-pack to the game Dungeon Master, in which you play as a fighter, ninja, wizard, or priest, and aim to collect all of the pieces of Corbum, from which Lord Chaos takes his power.


I haven't played it, so I hope that summarises it all right.

Unfortunately, I know nothing about this game, and the only description that seems to exist is the one quoted on the repo page there!
 
Last edited by a moderator:
Hi guys,


great that some people here volunteer to enhance descriptions! Thanks for that, in the name of all people who like to explore new software, even if they don't need it. Persons like me, who are curious enough to check out even packages with software they don't really need, will admire that!


However, my appeal actually went more towards the ones who build the PND packages.


I think, if you spent quite some time, maybe hours or days, porting software to the Pandora, optimizing it etc., then it's not a problem spending one more minute to fill the <description> field of the PXML.xml with a useful description.


But as a work around, I agree that the comment field of an application in the repo can be used to provide a better description.


I will also begin to improve description that way, whenever I encounter a package with a bad description and have a minute to do the work!


BTW: I just saw that not only the description should be meaningful, but also the package title. In PNDstore for example, you don't see the description, but only the package title. So I renamed my package with title "vnStat" to "vnStat Network Traffic Counter".


Unfortunately, only "vnStat Network Traffic" is shown on the Repo's summary (home) page. So I see it's also important to find short meaningful names. But I think a little consideration about the package title would also be good.


Daniel
 
Hi guys,
I think a little consideration about the package title would also be good.

Totally agree on both points, if we lead by example with some good descriptions then perhaps devs will follow.


I'm a casual browser of the repo to try and find out what on earth the gigabytes of apps I downloaded actually do, it's no easy task!
 
Some missing sample pics here and there should also help alot. :) A Picture can say more than thousand words.
When I did PCSX rearmed I thought about doing some screenshots, but then it came to me that copyrighted game screenshots can still be considered copyrighted material by themselves, or don't they?
 
great that some people here volunteer to enhance descriptions! Thanks for that, in the name of all people who like to explore new software, even if they don't need it. Persons like me, who are curious enough to check out even packages with software they don't really need, will admire that!
Just like Fusion_Power said, a focus on previewpics would help a lot for finding new, interesting PNDs.


I would even go so far as to suggest that previewpics should be considered at least as important as the textual description, and every PND should have at least four of them.


I also believe that the introduction of short videos would be the one best addition to any PND repository given the typical focus on multimedia content.

However, my appeal actually went more towards the ones who build the PND packages.
I believe the approach to achieve improvements is less than ideal then. It would probably be a good thing to create a short explanation of what a good description looks like, along with some negative examples, and sew that into the main ways developers put descriptions into their PNDs.

(...) I renamed my package with title "vnStat" to "vnStat Network Traffic Counter".


Unfortunately, only "vnStat Network Traffic" is shown on the Repo's summary (home) page. So I see it's also important to find short meaningful names.
I think that name fields should always be used for nothing but the actual name of the application. Would it make sense to introduce a dedicated short-description alongside the current longer <description> element?

When I did PCSX rearmed I thought about doing some screenshots, but then it came to me that copyrighted game screenshots can still be considered copyrighted material by themselves, or don't they?
More importantly, these screenshots would not display PCSx, but rather some random emulated games, which would be confusing as the package doesn't contain these games but an emulator.


edit-05feb2012-1836GMT+2: Before there was any software repository or the appstore, I began making a package manager that had a focus on screenshots for easier finding of new games. Here are some work-in-progress-ish guidelines for ideal screenshots that I had made back then:

  • Ideally, screenshot 0 of your game should show a typical (usually main-) menu (if applicable), screenshots 1 and 2 should show typical ingame action (if applicable), screenshot 3 should show ingame action, either typical or uncommon (if applicable). Only EITHER screenshot 2 or 3 should show something different if necessary. (unless any of that doesn't make sense in your particular case, of course)
  • Is your "game" a "utility" or some other kind of non-game? Use meaningful screenshots then. You should crop AND scale your screenshots so they reflect important "parts" of your software. Screenshots 0 and 3 should show parts which demonstrate what makes your software special (if applicable, otherwise treat them similar to screenshot 2), screenshot 2 should show a part that IN ADDITION shows the user what kind of software it is that you're giving her (text editor, emulator, media player, IDE...). Screenshot 1 should be focused solely on communicating what kind of software your software is (Any way to accomplish this is a good way in screenshot 1, as long as the user "gets the idea". Be creative and don't have fears to try out weird ideas in screenshot 1, but only do this if it's not a game or it WILL look silly!).



Thus, in my sometimes not so humble opinion, good previewpics for PCSx would be:

  • A zoomed-in part of the main emulator menu (I have never used PCSx, therefore I don't know whether this is applicable), since the most used user interface is immediately recognized by people familiar with the software.
  • An image that is not really a screenshot but makes immediately clear that PCSx is an emulator, without using the PCSx icon in that image.


</edit>
 
Last edited by a moderator:
Back
Top