Sp-dev-docs: Various issues in documentation

[MarkyDeParky]

First of all, thanks for documenting this. In general it really helps understanding the SharePoint Framework.

I've read the documentation on this page multiple times and there are quite a few things that I don't understand. I think they should be explained more clearly. Also, there are quite some typo's in the text that makes it harder to focus on the actual content.

A list of remarks I gathered so far:

-- About this paragraph (in the introduction of the article):
There are few different ways on getting your SharePoint Framework extensions deployed and activated on the SharePoint sites. Right model depends on your business requirements and objectives. Here are the main options.

-- It should probably be something like:
There are a few different ways of getting your SharePoint Framework extensions deployed and activated on SharePoint sites. Choosing the right way depends on your business requirements and objectives. Here are the main options.

========

-- This bullet (in the introduction of the article):

• Activate extension on specific site using feature framework based activation when solution is installed. This is the only model which supports site level assets getting created or deployed as part of the solution activation.

-- Should be something like:

• Activate an extension on a specific site using feature framework based activation when a solution is installed. This is the only model that supports site level assets getting created or deployed as part of the solution activation.

========

-- About the following two options (in the introduction of the article):

• Use tenant-scoped deployment option and activate the extension on specific sites using PowerShell or APIs. This capability was introduced with SharePoint Framework version 1.4 release.
• Use tenant wide deployment option for extensions from app catalog. This capability was introduced with SharePoint Framework version 1.6 release.

-- It is unclear to me what the difference is between tenant-scoped deployment and tenant wide deployment. Please elaborate.

========

-- About the following paragraph (in 'Package the Hello World Application Customizer'):
In this case we will be activating the extension specifically in a single site, which means that we'll be using Feature Framework based activation when the solution is being installed on the site.

-- Are we talking "site" as "site collection" or "web" here? Later in the documentation, it states that the Application Customizer has a "Web scoped feature by default". Please use consistent terminology, especially in one article.

========

-- About the following paragraph (in step 2 of 'Package the Hello World Application Customizer'):
Unlike in Debug mode, to use an extension on modern SharePoint pages, you need to deploy and register the extension with SharePoint in Site collection, Site, or List scope. The scope defines where and how the Application Customizer is active. In this particular scenario, we'll register the Application Customizer by using the Site collection scope.

-- It states that in this scenario, we use Site Collection scope. Later in the article it says [Because this elements.xml is associated to a Web scoped feature by default, this CustomAction is automatically added to the Web.UserCustomAction collection in the site where the solution is being installed.]. This seems to be inconsistent.

=======

-- About the following paragraph (in step 3 of 'Package the Hello World Application Customizer'):

1. Install the solution package to the site where it should be installed so that the extension manifest is being white listed for execution.

-- It's not clear to me what is meant to be done here. It seems that this step isn't supposed to be here, since we haven't even packaged the solution at this stage yet.

=======

-- About the following sentence (in step 4 of 'Package the Hello World Application Customizer'):
Associate the Application Customizer to the planned scope. This can be performed programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package.

-- Please provide more information about when to use CSOM/REST to do this and provide examples on how to do this (maybe in a different article)

=======

-- About the following bullets (in step 4 of 'Package the Hello World Application Customizer'):

• ClientSideComponentId. This is the identifier (GUID) of the Field Customizer, which has been installed in the app catalog.
• ClientSideComponentProperties. This is an optional parameter, which can be used to provide properties for the Field Customizer instance.

-- Where does the Field Customizer come from? Following steps 1 and 2 we currently have an Application Customizer, not a Field Customizer. This is very confusing.

=======

-- About the following paragraph (in step 4 of 'Package the Hello World Application Customizer'):
Note that you can control the requirement to add a solution containing your extension to the site by using the skipFeatureDeployment setting in package-solution.json. Even though you would not require the solution to be installed on the site, you need to associate ClientSideComponentId to specific objects for the extension to be visible.

-- I don't understand what "you can control the requirement to add a solution containing your extension to the site" means. Please elaborate.
-- Please explain more clearly what the "skipFeatureDeployment" property does and when to use it.
-- I don't understand what "you need to associate ClientSideComponentId to specific objects for the extension to be visible." means. Please explain more clearly what the purpose of these properties is.

=======

-- About the following paragraph (in step 6 of 'Package the Hello World Application Customizer'):
Extend the sharepoint folder and assets subfolder in the root of the solution to see the existing elements.xml file.

-- This should be
Expand the sharepoint folder and assets sub folder in the root of the solution to see the existing elements.xml file.

=======

-- About the following paragraph
ClientSideComponentProperties has also been automatically set with the default structure and JSON properties for this extension instance. Note how the JSON is escaped so that we can set it properly within an XML attribute.

-- The right term would be "encoded", instead of "escaped"

=======

-- About the following paragraph
Tenant Wide Extensions list can be used to automatically activate extensions in tenant from a centralized location. Tenant wide deployment is supported for Application customizers and list view command sets. You can specific different target definitions, like activation based on the site type or list type.

-- This paragraph can be left out completely as it doesn't apply to the scope of this article (site collection scope). Also, more details about tenant wide deployment are in a different article anyway.

=======

-- About the following paragraph
Your package-solution.json should look somewhat following after the needed edits, except for the id entries, which will be specific for your solution.

-- This should be something like
Your package-solution.json should look something like the following after the needed edits, except for the id entries, which will be specific for your solution.

=======

In general, it would also be helpful to know more about the possibilities to activate an extension on web or list level. In what scenarios would you do that and how?

---

Document Details

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

• ID: f46bf1b1-6910-2905-43ad-d24d88ef05e3
• Version Independent ID: f74fc1df-0ae6-6f5b-5008-9e95922faa9d
• Content: Deploy your extension to SharePoint (Hello World part 3)
• Content Source: docs/spfx/extensions/get-started/serving-your-extension-from-sharepoint.md
• Product: sharepoint
• GitHub Login: @spdevdocs
• Microsoft Alias: spdevdocs

[msft-github-bot]

Thank you for reporting this issue. We will be triaging your incoming issue as soon as possible.

[andrewconnell]

Thanks for the feedback... but would you care to submit a PR to fix the doc with the suggestions you referenced?

[piotr-kasprzyk]

For me the instructions are also unclear. As for the PR request from Andrew - if somebody says they do not know how to do it basing on your instructions, how do you expect them to prepare correct instructions? We are learning here, not teaching.

Regards,

Piotr

[andrewconnell]

@piotr-kasprzyk - the OP had suggestions for changes to the doc, so I was simply saying "would you like to go ahead and contribute?".

I was in no way asking someone to write docs on how to do something if they didn't know how to do it..

[msft-github-bot]

This issue is being closed as part of an issue list cleanup project. Issues with no activity in the past 6 months that aren't tracked by engineering as bugs were closed as part of this inititive. If this is still an issue, please follow the steps outlined to re-open the issue.