search

dotnet / docs

This repository contains .NET Documentation.
https://learn.microsoft.com/dotnet
Creative Commons Attribution 4.0 International
4.29k stars 5.92k forks source link

NuGet Authors - documentation is unclear #20827

Open skrysmanski opened 4 years ago

skrysmanski commented 4 years ago

This page describes the <Authors> property like this:

A semicolon-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.

I have the following "complaints" about this:

  1. It says "profile names" but it's not really clear what a "profile name" actually is. I first thought that this would mean "user name" (like "skrysmanski" instead of "Sebastian Krysmanski"); but then I had a look at some of the more popular NuGet packages (like Newtonsoft.Json) and they use "display names" (e.g. "James Newton-King"). I think the wording here should be more clear or an example should be given. The same applies to the related section in the .nuspec File Reference.
  2. Not sure whether this is a bug or not but this page defines this property as "A semicolon-separated list of packages authors" while the .nuspec File Reference defines it as "A comma-separated list of packages authors".
  3. It also says: "These are [...] used to cross-reference packages by the same authors.". Is that really the case? At least on nuget.org this property is simply displayed as (unclickable) text - and the owners are used for this "cross-reference". The same applies to the related section in the .nuspec File Reference.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

tdykstra commented 4 years ago

@skrysmanski Thanks for pointing that out. I'm putting this on our backlog and we'll leave the issue open until it's addressed.