A few thoughts on recipes' SUMMARY / DESCRIPTION

Software
1

The SUMMARY of a haikuports recipe is the short sentence appearing in HaikuDepot’s package list.
The DESCRIPTION is the longer text you see in HaikUDepot when selecting a package from the list.
I happen to see many packages because I try to keep up with the German translation of at least the enduser GUI applications, and add screenshots, icons, categories where missing. There are a few things I wanted to point out to the brave bunch of people writing all those recipes:

I know it’s easy - and most of the time totally OK - to go to the software’s homepage and copy & paste some text. One has to be mindful of a few things though:

  • Limit yourself to list just a handful of the main features.
    No HaikUDepot user appreciates a wall of text (more importantly, I as translator, don’t either :smiley: ). The homepage of the software is linked in HaikuDepot, so all details are just a click away.
  • Make sure the DESCRIPTION is relevant
    Remove features not available for Haiku. Don’t bore us with the history of the development or license changes etc. If it’s a game, describe the game play etc. but don’t dwell on who bought what and published it when and how…
  • Also, if a game needs data that has to be downloaded/purchase somewhere or is only available on the DVD the game originally came with, do mention that.
  • If the supported platforms are listed, don’t forget to add “Haiku”… :slight_smile:
  • Don’t mention the license or used framework or that this software runs on Haiku; users don’t care about that. So no “A Qt tool to manage music on Haiku, written in C++” please.
  • Most importantly: HaikuDepot’s full-text search can only find the words used in the SUMMARY / DESCRIPTION. Take a minute and imagine what search terms users might use when they’re interested in that kind of software. Andrew is looking into adding additional KEYWORDS, which will make it easier. Until then, try to insert those potential search terms in the text, if they’re not there already.

Anyone who wants to add their pet peeve? :slight_smile:

8 Likes
2

One thing I do is use “repology” to see how other OS’s use their DESCRIPTION/SUMMARY before I copy/paste the information on their website.
If a port is supported, I try to uptream (eventual) patches
On a sidenote, IIRC SUMMARY shouldn’t contain the actual name (eg SUMMARY="project* … ") where DESCRIPTION can use it? (DESCRIPTION="project* …)

3

Yep. That’s already in the HaikuPorter Guidelines.

5

Maybe a chance to add a “Changelog” into the recipes would be a good idea too? (if provided by the source)

6

A changelog is kept at HaikuDepotServer. I’m not sure what criteria determine what’s part of the recipe and what’s curated at HaikuDepotServer…

In any case, this thread was meant to collect “best practices” when it comes to the current summary/description fields, not possible enhancements of the HDS/recipe system itself.

1 Like