Improve Task Documentation

[JFolberth]

There is a significant gap in parameter input documentation.

Currently the only place to find this information I am aware of is through the UI and hover over the info indicators:

This is a huge learning curve/hurtle for customer adoption.

Here is an example from other MS tasks: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/azure-resource-manager-template-deployment-v3?view=azure-pipelines

# ARM template deployment v3
# Deploy an Azure Resource Manager (ARM) template to all the deployment scopes.
- task: AzureResourceManagerTemplateDeployment@3
  inputs:
  # Azure Details
    deploymentScope: 'Resource Group' # 'Management Group' | 'Subscription' | 'Resource Group'. Required. Deployment scope. Default: Resource Group.
    azureResourceManagerConnection: # string. Alias: ConnectedServiceName. Required. Azure Resource Manager connection. 
    #subscriptionId: # string. Alias: subscriptionName. Required when deploymentScope != Management Group. Subscription. 
    #action: 'Create Or Update Resource Group' # 'Create Or Update Resource Group' | 'DeleteRG'. Required when deploymentScope = Resource Group. Action. Default: Create Or Update Resource Group.
    #resourceGroupName: # string. Required when deploymentScope = Resource Group. Resource group. 
    #location: # string. Required when action = Create Or Update Resource Group || deploymentScope != Resource Group. Location. 
  # Template
    #templateLocation: 'Linked artifact' # 'Linked artifact' | 'URL of the file'. Required when action = Create Or Update Resource Group || deploymentScope != Resource Group. Template location. Default: Linked artifact.
    #csmFileLink: # string. Required when templateLocation = URL of the file && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template link. 
    #csmParametersFileLink: # string. Optional. Use when templateLocation = URL of the file && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template parameters link. 
    #csmFile: # string. Required when templateLocation = Linked artifact && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template. 
    #csmParametersFile: # string. Optional. Use when templateLocation = Linked artifact && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template parameters. 
    #overrideParameters: # string. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Override template parameters. 
    #deploymentMode: 'Incremental' # 'Incremental' | 'Complete' | 'Validation'. Required when action = Create Or Update Resource Group || deploymentScope != Resource Group. Deployment mode. Default: Incremental.
  # Advanced
    #deploymentName: # string. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Deployment name. 
    #deploymentOutputs: # string. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Deployment outputs. 
    #addSpnToEnvironment: false # boolean. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Access service principal details in override parameters. Default: false.

[JiandongJiang]

Thanks for the feedback. I will bring it up for team's attention for prioritization.

[JFolberth]

@JiandongJiang has there been anymore thought on this as without this documentation the product does not feel complete or ready for mass consumption.

[JiandongJiang]

Yes, our team ack'd it and was prioritizing it for documentation improvements. Thanks.

[fabio-s-franco]

@JiandongJiang There is literally nothing of documentation on how to use this besides the bear mention on how to add the extension without any configuration:

https://learn.microsoft.com/en-us/azure/defender-for-cloud/azure-devops-extension#configure-your-pipelines-using-yaml

8. Paste the following YAML into the pipeline:

# Starter pipeline
# Start with a minimal pipeline that you can customize to build and deploy your code.
# Add steps that build, run tests, deploy, and more:
# https://aka.ms/yaml
trigger: none
pool:
 vmImage: 'windows-latest'
steps:
- task: MicrosoftSecurityDevOps@1
 displayName: 'Microsoft Security DevOps'

Which makes this practically impossible to adopt.

[JiandongJiang]

@fabio-s-franco , thanks for the feedback. Our team ack'd it and is working on the documentation improvements. Thanks.

[JFolberth]

@JiandongJiang unfortunately it's responses like this in addition to lack of engagement, see issues and PRs, that leads me to steer customers away from Defender for DevOps and prioritize other solutions that fill this technology gap.

[JiandongJiang]

The requested updates to the mentioned documentation will be deployed soon per schedule. Our PM @sukhans will be updating this thread for closure once the updates go live. Thanks.

[fabio-s-franco]

@JFolberth I don't have issues with the response itself, I am sure @JiandongJiang is doing what's within his reach. But I do agree. The lack of engagement and very poor management leads to this. Half baked, solutions that don't get enough attention.

I already moved on, there is no way I am gonna spend energy here. If it takes months to add simple documentation, what should I expect if I run into issues. Thank you, but no thank you.

[charlesoxyer]

Hi @JFolberth, @fabio-s-franco, my name is Charles Oxyer, and I first want to apologize for the slow and unacceptable response time in this matter. I am taking over PM responsibilities for the MSDO task, and first want to let you know the parameter inputs are documented here: https://github.com/microsoft/security-devops-azdevops/wiki#msdo-task-configuration and will be included as part of a full documentation overhaul we are working on for the DevOps security features in Defender for Cloud documentation.

If you are willing to give DevOps security in Defender for Cloud a second chance, you can reach out directly to me with feedback/issues you encounter and I hope the capabilities we continue to ship over the coming months change your mind about our product. [my_github_username]@microsoft.com.