[idea] Guidelines for package description (discuss)

[Redsandro]

"Now" that the Chocolatey gallery supports markdown (it has been for a long time, but it's taking off in the sense that more and more packages actually make use of it), it is more interesting to spice up the gallery.

I've experimentally added some screenshots to some package descriptions, and it makes the gallery look awesome.

E.g.:

• TouchDesigner (personal repo)
• Blender (core team repo)

1.

What do you think about encouraging people to add one or two semi-resized screenshots in the package description?

:information_source: We should structurally have a (maximum) width of 640 pixels on screenshots (or something else that makes sense, as long as it's structurally the same).

2.

I've hosted some experimental screenshots on imgur, but structurally using imgur as a CDN is against their TOS.

:information_source: We could host screenshots similar to the way we host icons for packages in this repository.

For example, we could make relevant packages have a images or screenshots, or more versatile and multi-purpose assets subdirectory.

:information_source: I was never a fan of separating icons from packages. I prefer having all related assets in a single package directory. However, this repo decided to go another way, so you might want to do the same with package assets like screenshots.

3.

We could write the description in a separate description.md or README.md (so github shows it too) inside the package directory, and have AU automatically copy the description unto the nuspec. This way, it becomes easier to view and edit the gallery markdown description.

[AdmiringWorm]

Personally I'm not really sold on this, well not with the two example you gave at least.

Sure it looks good and all, but lets look at the TouchDesigner. This is a program I've never even heard of, so I open it and see a bunch of images. Well this looks nice and all, but three images don't tell me anything other than that the program looks good. What does it do, why would I use it? Sure you have three lines of description which tells a little about the program, but these three lines are almost invisible because of the images. Because of this, even if I was interested in the program I would probably skip this package and look for something else.

I don't disagree with using images though, but these should be used sparingly (IMO) and rather supplement the description, instead of being the first thing you see (and possibly the only, if you don't look closely enough). It doesn't matter how good the page looks, if it doesn't give you the information you need.

Just my 2 cents.

[Redsandro]

I agree the description (as in text) of these examples (and nearly all packages) could be (a lot) better.

However, what I'm missing in general is graphics. Visual communication. You have three kinds of people. Text people, visual people, and the visually impaired, who are, in this sense, visual people, because they too prefer visual communication over text.

Let's take myself for example. I am slightly visually impaired. (I studied communication, had an accident, and now I hate text (and developers that use long variable names).) That's probably why I (personally) don't spend much time on writing good descriptions. I skip them. Why I don't read books but listen to audio books every day.

It's why I tried to shorten sentences and bold keywords in the (first incarnation of) the package guidelines, and why I'm horrified to see how elaborate the text is now. It's why I proposed ideas and PRs to make early versions of chocolatey less verbose and use colors.

I want to recognize something immediately in a visual way. For nearly 100% of chocolatey packages there is no graphics at all. If I don't know a package, I don't read the description unless it's short and spacey formatted. Otherwise I type ctrl+t i <software name> and my browser shows a google image search.

(I can tell you that the chocolatey website is accessibility unfriendly, but then again most of the internet is.)

But even among non-visually-impaired people. I learned that 40% of people prefer a visual recognition over text alone. 60% of people don't care or actually prefer no graphics, just information.

That said;

I don't disagree with using images though, but these should be used sparingly (IMO) and rather supplement the description, instead of being the first thing you see

I was proposing to use images in general, not specifically the way I did it. This repository seems to have higher packaging standards than chocolatey itself, so I was wondering if some kind of thought process could be devoted to making a suggestion or guideline that works for everyone. In my subjective opinion, every non-cli package should have at least 1 screenshot. I don't mind it's location. It can very well be supplementary, but it should also work on it's own. :smiley:

PS - TouchDesigner is specialistic software with a target audience that probably actively look for the software. The first image tells people who work with node-based compositing a lot of things. The third one (although accidentally the wrong one) shows immedately signal-based processing. You are clearly a text person and not the target audience for this software if all you learn from this is that "it looks good". :laughing:

[AdmiringWorm]

I do agree that there should be some kind of guidelines when it comes to use of screenshots in the description, and also mostly agree with the 3 points you had in your original text (I think 640px is a little large though, but that is probably just me). The third point may not be possible right now without some custom logic though, as AU uses the built-in replacement logic after reading the content with Get-Content (this reads it line by line and puts it all into an array, making multiline replacements impossible).

You are clearly a text person and not the target audience for this software if all you learn from this is that "it looks good". 😆

You're correct there, I'm mostly a text person (although I don't like pages of pure text though). As such, I'm probably not even the right person for a discussion like this so let us try bringing in the crowd to get their opinion.

/cc @chocolatey/chocolateycommunitypackages

[Redsandro]

You're correct there, I'm mostly a text person (although I don't like pages of pure text though). As such, I'm probably not even the right person for a discussion like this

Your weighing in is appreciated either way. Your concerns resonate with at least 60% of the users.

[majkinetor]

What do you think about encouraging people to add one or two semi-resized screenshots in the package description?

I suggested to @ferventcoder already that more stuff should be there in the package, including screenshots and way to reference them in the description. So yeah, I think its good idea. I keep single screenshot for my packages in my personal repo (see here example). I prefer to keep everything in package folder. I always use the same names too - icon & screenshot (so I never have multiple screenshots, one is probably enough for majority of tools). I don't see much point in icon mumbo jumbo as it is now versus black boxing the package with all its stuff. Separating icons and other stuff is just plain wrong.

About your README.md to be copied in description, that is great idea, becose Github becomes another interface to your packages and AU status page indexer - you already jump directly to source from there if you click NuSpec version link and this one will show entire description. So its awesome idea.

About the concern that images would make text second level citizen - while it might be true 99% of users probably want to see images, then text, me included (I use cli even to play music and surf the web) - and its nothing that can't be solved easily. I do think that this requires a bit of planning. The problem is that Github is not very nice with images - you can't limit their size for example AFAIK.

TLDR, I agree 100%.

[majkinetor]

@Redsandro , @AdmiringWorm, @pascalberger , @ferventcoder

I implemented PoC of README.md to description in my copyq package: https://github.com/majkinetor/au-packages/tree/master/copyq

See the relevant code.

[majkinetor]

Note that you can cherry pick from the readme. I skipped first 2 lines.

[Redsandro]

I implemented PoC of README.md to description in my copyq package

Yes! Exactly! Thanks for doing this. I couldn't figure out how to do that mutli-line replace from file. I'm going to implement that with my packages when I have some time.

Would love to have this the new standard for core team packages, because it makes editing the description easier and quickly glance the resulting markdown from viewing the source page.

[gep13]

@Redsandro said... because it makes editing the description easier and quickly glance the resulting markdown from viewing the source page.

Bear in mind that what you see rendered in GitHub might not be exactly the same as you see in the Gallery. Both (at the minute anyway) use different engines to parse and render the markdown, so there may be some things that work in GitHub and not on the site, and vice versa.

[Redsandro]

@gep13 Markdown being semantics, the formatting difference is okay. We just need to stay away from the unsupported "github flavored" part.

[majkinetor]

I couldn't figure out how to do that mutli-line replace from file. I'm going to implement that with my packages when I have some time.

Multi-line replacement is not possible in au_SearchReplace, it had to be done this way.

I'm going to implement that with my packages when I have some time.

Maybe you should wait a week or so. I will see how to implement it as AU plugin, will require AU changes tho as plugins are currently run at the end (can be done now in BeforeEach only, something I would like to avoid).

Would love to have this the new standard for core team packages, because it makes editing the description easier and quickly glance the resulting markdown from viewing the source page.

I agree. Not only its easier, it provides visual feedback on description before it is sent to gallery and provides additional interface. In company, for example, you could use this as zero conf interface to your local packages and makes you less dependent on gallery.

Bear in mind that what you see rendered in GitHub might not be exactly the same as you see in the Gallery

Its still better then nothing and gallery markdown parser and css style sux. I would rather always look at the Github README.md. Now I can.

[pascalberger]

Markdown being semantics, the formatting difference is okay. We just need to stay away from the unsupported "github flavored" part.

It's not only about GFM, there are other parts which are rendered differently, eg. chocolatey.org takes newlines into account.

[majkinetor]

OK, I commited Set-DescriptionFromReadme function that can be used like this (NOTE: I had an error above, it can't be used in BeforeUpdate because it gets reverted).

To use it, simply source this function in the updater:

. $PSScriptRoot\..\..\scripts\Set-DescriptionFromReadme.ps1

2 Parameters lets you skip lines from start and end of the README.md file which might come in handy for different situations (i.e. more screenshots in the README.md etc.) I wont create AU plugin because this is way easier and it doesn't fit the plugin workflow in the way I am comfortable with.

[Redsandro]

@majkinetor good work. It will be some time until I update things. If you change your implementation or decide to update au, please let us know here so I can look over this when I get around to updating my packages.

@pascalberger said:

chocolatey.org takes newlines into account.

That would be a bug with chocolatey.org or it's parser or it's parsers' settings. Swallowing newlines and inserting newlines at double spaces is the (odd or not) specification.

[ferventcoder]

That would be a bug with chocolatey.org or it's parser or it's parsers' settings. Swallowing newlines and inserting newlines at double spaces is the (odd or not) specification.

I don't know that it is a bug - because with markdown you need two spaces at the end of a line to signify a line break (or an empty line in between), otherwise you get a single line for everything that is not a heading or a list. And that would look like more arse than it might right now.

[majkinetor]

I don't know that it is a bug - because with markdown you need two spaces at the end of a line to signify a line break (or an empty line in between)

2 spaces -> new line empty line -> new paragraph

[AdmiringWorm]

@ferventcoder said otherwise you get a single line for everything that is not a heading or a list. And that would look like more arse than it might right now.

I completely disagree with that. With how it is currently it actually looks like more arse than it would be when using soft breaklines. Also if using soft breaklines the description would be adaptable if the layout on the chocolatey package page is ever changed (and possibly changed to be able to handle both desktops with different screen sizes, mobiles, tablets, etc.) When using hard breaklines it's a constant struggle currently with trying to have the formatting in the nuspec file, and the description on the chocolatey website to look good (unless you know the magical character length in the description on the website, I think it is ~128 characters right now)

If a maintainer absolutely needs a new line, then IMO (s)he should opt-in with appending 2 spaces to the line, instead of forcing hard breaklines on everyone without a chance to opt-out of it.

[ferventcoder]

@AdmiringWorm explain the difference between a soft break and a hard break please.

Description is 4,000 character limit.

[ferventcoder]

Also keep in mind, these things were tested when this was first added to the site a few years ago, and it did look rather bad without adding in automatic line breaks to flow more like the way the package description was done in the nuspec. So whether that is the case now or not, that serves for the current discussion.

[AdmiringWorm]

@AdmiringWorm explain the difference between a soft break and a hard break please.

I'm not good at explaining things, but I'll try. A soft break is when the new line is ignored when displayed in the intended context, but is respected when displayed in for instance an editor. While hard breaks are respected both when displayed in the intended context, and in the an editor (which only works well if both uses the same line length restriction, IMO).

Description is 4,000 character limit.

I did not mean the total description length, but rather how many characters can fit in one line with the current column width.

Also keep in mind, these things were tested when this was first added to the site a few years ago, and it did look rather bad without adding in automatic line breaks to flow more like the way the package description was done in the nuspec. So whether that is the case now or not, that serves for the current discussion.

It probably worked well back then. I can't really say as I don't know how the layout of chocolatey.org was then. But lets take an example on how it is now with the notepad++ package. The description on chocolatey.org doesn't look all that bad with how it is now, but that is mainly because line breaks isn't used in the nuspec file and looks terrible in the nuspec file with the overlowing text (except if you use a editor that supports soft new lines). If we had been following the guidelines as per 2.2 Formatting these lines should be a maximum of 150 characters, which would then possibly make it look awful on chocolatey.org (mainly a because a single word could possibly be placed on its own line)

/cc @ferventcoder

[Redsandro]

@ferventcoder said:

these things were tested when this was first added to the site a few years ago, and it did look rather bad without adding in automatic line breaks to flow more like the way the package description was done in the nuspec.

Ah, so it's like nl2br added prior to markdown, and now markdown added on top with it's own spec for using newlines, mixing all the newline methods.

Personally I think one should embrace a spec fully or not at all. So in my opinion, it is time to choose for markdown, and remove all nl2br and auto-br functions. Add a guideline for package moderators to watch for hideous descriptions and once observed instruct package maintainers to re-flow their description before the next push will be approved.

Quick fixes would be to add double trailing spaces or an empty line between nuspec description lines.

Markdown spec:

roses are red¶
violets are blue¶

roses are red violets are blue

roses are red  ¶
violets are blue¶

roses are red violets are blue

roses are red¶
¶
violets are blue¶

roses are red

violets are blue

See also: Wikipedia.

Note that github flavored markdown also adds <br> on newlines, so you don't need the two spaces, as opposed to e.g. Stack Overflow who's staying closer to the spec. You can optionally decide to keep this, but not the newline on arbitrary character length, because having 4 ways to add newlines renders text into an uncomfortable newline party.

¶ :tada: ¶ :balloon: ¶ :birthday: ¶

On second thought.. that newline party does look rather companionable.

[AdmiringWorm]

Note that github flavored markdown also adds <br> on newlines, so you don't need the two spaces, as opposed to e.g. Stack Overflow who's staying closer to the spec.

I think github only do that for comments, for .md files they don't add <br>.

[ferventcoder]

If we had been following the guidelines as per 2.2 Formatting these lines should be a maximum of 150 characters

Sounds like we need to fix the guideline. I don't agree that there should be any formatting in the file itself (the line breaks at 150 chars) - that's what wrapping is for. And if you go for a maximum of 150 chars and the site layout changes later, I don't want to suddenly have thousands of packages that look bad because of it.

[ferventcoder]

but not the newline on arbitrary character length

👍

[ferventcoder]

It may not be a bad idea to open these kinds of things up for debate to see what we can technically do and what is best. Those guidelines were not necessarily written by someone that knew all of the constraints everywhere.

[ferventcoder]

I think that is what the purpose of this discussion is about, but I mean probably reviewing the guidelines that are published. I would not have agreed with that 150 line break idea.

[ferventcoder]

You can't suddenly want to go a different direction without making other packaging look bad. So it's not a choice someone gets to make suddenly. We have to operate at a slower speed to allow for community transition.

[AdmiringWorm]

I don't agree that there should be any formatting in the file itself (the line breaks at 150 chars) - that's what wrapping is for.

Personally I think it should, however that argument could be used for chocolatey.org as well. Considering it already do formatting when a line is longer than the package column width (in that sense, wrapping the line), so no need to force hard new line breaks by default.

I think that is what the purpose of this discussion is about, but I mean probably reviewing the guidelines that are published. I would not have agreed with that 150 line break idea.

sorry, I was reading the guidelines wrong. it specifically says for scripts.

You can't suddenly want to go a different direction without making other packaging look bad. So it's not a choice someone gets to make suddenly. We have to operate at a slower speed to allow for community transition.

I agree that we can't suddenly go a different direction, and need to take it at a slower speed. But I do think it is something worth considering, and perhaps open up for debate for all maintainers (not just for those monitoring the core team repo)

[Redsandro]

Apart from giving my 2 cents in my previous comment, I think I don't really understand the rules (programatically in the gallery) as it is now.

Can someone provide a specific example of a nuspec description and how it is after being converted to chocolatey-style non-markdown newlines juxtaposed against spec markdown? I believe you when you say it looks bad @ferventcoder but I can't imagine how it's bad. Two newlines in nuspec would also be a paragraph in markdown.

So either I don't fully get the problem (probably) or a solution is not too difficult.

[majkinetor]

Nothing that some CSS wouldn't solve apparently. Totally agree with @Redsandro - over-complication happens again,

[ferventcoder]

@Redsandro it's using MarkdownSharp (although we've started to implement Markdig in some areas, it is a great replacement) and we've added in the bit for adding a line break when there is a line break in the text (nl2br you called it?). The other aspect was that formatting in the nuspec is already four spaces in and we didn't want the gallery to render that was a code block, so we shut that off. That's about it.

Two empty lines is likely to end up with a new paragraph as that is part of the spec.

[Redsandro]

@ferventcoder perhaps we could add some other workarounds in the description processing code to remove or greatly reduce "broken descriptions"?

• If all lines are indented with the same amount of white space, remove this white space.
• If block-level markdown is detected (e.g. regex for /#{1,4}\s/ (header), /^-{3,}/ (ruler/header 2), /^={3,}/ (header 1), /^\*\s/ and /^-\s/ (list-items), /\^`{3}/ (code block) etc), do not add nl2br.