search

Cape-Code / vsts-time-and-effort

Easily plan & track time, costs, and budgets on work items.
https://marketplace.visualstudio.com/items?itemName=capecode.cc-time-and-effort
MIT License
11 stars 3 forks source link

Making VSTS Extension documentation better #7

Open mmanela opened 6 years ago

mmanela commented 6 years ago

Hi there, I saw on the bottom of your marketplace entry the following line

Developing and testing extensions for VSTS is challenging, because the provided documentation is incomplete and not 100% up-to-date

I work on the VSTS team and we are committed to making the documentation and integration better. Would you please detail what information was wrong and what you felt was missing so we can improve it?

Thanks!

cc-fabianvo commented 6 years ago

Hi, thanks for contacting us. Here are some of the problems I encountered while developing this extension.

Documentation

  1. No MSDN style API reference (especially for UI controls) For example Grid reference is almost empty, the Typescript typings file has some more information about IGridOptions, but not for all attributes. Also just looking at the typings file there are many UI controls, which are not documented at all.

  2. The extension point documentation is incomplete (this extension uses an undocumented extension point ms.vss-web.action-provider, which I only found out about through searching all supplied example Github projects) -- I tried using ms.vss-work-web.query-result-work-item-menu for the context menu, but that did not work at all. It would be really helpful to be able to query an VSTS instance for all available extension points (maybe similar to the 'menu group hack') -- I know there is an extension, but it is not up-to-date.

  3. The VSS SDK documentation needs improvement -- especially VSS.register -- Extension points should have types (or interfaces) and it should be well documented, which extension point takes what kind of a parameter instead of just listing it as"".

  4. The README on the Extension SDK Github repository is way more helpful than the Quickstart tutorial.

Development / Integration

Finally, here are some things that would have improved my development workflow, enabled features, or improved performance of the extension:

  1. Access to some kind of logging/telemetry service would be great
  2. Need a complete how-to on local development and testing of an extension to improve the workflow -- ideally as a Github repository, which a developer only needs to clone to get started
  3. Allow me to create a contribution that listens to work item changes outside the work item form without using an external service including bulk operations (would lead to massive performance improvements, because we could cache the rolled-up data and change it when items are moved to a different parent)

I hope this helps to clarify some of the issues.

mmanela commented 6 years ago

Thanks for the feedback. I will take this back to the team and make improvements.

One item I want to follow up on is around the work item form. For the context menu you said you tried ms.vss-work-web.query-result-work-item-menu and it did not work. Can you explain more? Where did you want it to show? Did it not show up? @cc-fabianvo