Add documentation with platform specific recommendations

[mrlacey]

Add documentation for each "device family" with common (or recommended?) suggestions for improvements, enhancements, etc. that can be made.

X-Ref #903

[paulio]

+1 for this. I'd like to see a separate breadcrumb-like document for each recommendation. E.g. if you choose Toast Support then you have a section "Toast Support" then an explanation of the code added, e.g. Creating a Toast, handling a Toast, etc. Currently the code is dotted around the project and you have follow the call-tree to try and understand it.

[mrlacey]

@paulio I think you're asking for something else. What we don't want to be doing is duplicating existing documentation or writing our own version of it. The goal with documentation in WTS is to point existing information where appropriate. Where we are providing documentation it's specific to something we do in the WTS specific code.

If you want to know about "Toast Support" you should understand what it is and the basics of how it works before adding it to a project.

In terms of the Toast Notification feature, the generated code already includes this link: https://blogs.msdn.microsoft.com/tiles_and_toasts/2015/07/08/quickstart-sending-a-local-toast-notification-and-handling-activations-from-it-windows-10/

And then in the sample, links to documentation to relevant parts of the toast content are also provided.
https://developer.microsoft.com/en-us/windows/uwp-community-toolkit/api/microsoft_toolkit_uwp_notifications_toastcontent
https://developer.microsoft.com/en-us/windows/uwp-community-toolkit/api/microsoft_toolkit_uwp_notifications_toastbutton
https://docs.microsoft.com/en-gb/uwp/api/windows.ui.notifications.toastnotification#Windows_UI_Notifications_ToastNotification_Tag

If there are specific issues with understanding the page and feature options, we should look to improve the existing documentation rather than create more of it.

If you think there specific options that are poorly documented in the generated code or there are alternative links to documentation that would be better than what we're using we can change them.
Your request seems to be that we should provide an additional documentation summary for all page and feature options. This seems very broad and of questionable benefit.

This is also very different from the original subject of this issue. In future, please open new issues to discuss different topics.

[mrlacey]

Returning to the original subject of this issue.

The aim is to document additional steps that could be taken to further modify a generated project to improve the app experience on specific types of device. The document is expected to mostly be a list of links to official documentation

Below are a few suggestions but the list should be fleshed out a bit more before this is created.

Mobile

• Customize the status bar
• Customize the Comand Bar

Desktop

• ????

XBox

• Support the gamepad controller
• Change pointer mode

Mixed Reality

• Add 3D icon

At least some of the items mentioned here could, potentially, be added as separate templates in the future if there was sufficient demand.

[touseefbsb]

@mrlacey how about generating tailored pages for each device type and out TODOs on all those pages in comments so that each device specific views can be better adapted on each device , i.e Tailored Design and this can be added as an optional feature in the wts wizard.
https://docs.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml#tailored-layouts
creating the folders for each device within the Views folder looks appropiate way to do this. what do you think?

[mrlacey]

@touseefbsb There are several potential issues with what you're asking for:

• What is the specific issue you're trying to address with this? (Or is it just an idea about a nice-to-have?)
• Are you proposing this apply to all pages in a project or just some?
• If adding this to an existing project, should all existing pages have variations added?
• If this was set for a previously generated project, should any pages added later have this applied automatically too?
• The general design guidance is to try and create a single view that adapts to different device needs. It should be the exception to need device specific pages. Providing the functionality you describe may encourage bad practices.
• If needing a device-specific version of every view in an app then a different structure for the app may be required. The knowledge of application-specific requirements for the most appropriate project/solution structure are more than could be easily handled in a tool like WTS.
• There are different ways of creating device-family specific versions of views. This can be done with directory names or file names. Different app requirements and personal preferences may lead to scenarios where one is more appropriate than the other. Providing options for both would be a lot of work. Dynamically trying to infer which approach to use would be error-prone.
• Very few projects need to run on every device family. Even fewer need to customize for all of them. How widely would this be used?
• What would go in the family-specific version of each view? What could we put in it them to make their value obvious and to make it clear that a different version is being used?
• What would go in the TODO comments you mention? Would they all be the same "Add a device family-specific version of this page" or would they be tailored for each page/device family?
• How would such functionality be tested? Very few people have access to devices of all families. (As much as I'd like an excuse to get a SurfaceHub and HoloLens I don't think this is it.) Automating testing on each device family would also require customizing hardware to make it possible to run all necessary test remotely. If testing on specific hardware was a requirement it would also raise the barrier to contribute to WTS and we'd like to make contributing easier not harder.

There's another extension available that will add the platform-specific folders for you. Are you aware of this? Does it solve your specific needs?
https://marketplace.visualstudio.com/items?itemName=OlivierMatis.DeviceFamilyAdaptiveXAMLTool

Full disclosure. I forgot about this issue when I raised #2089 (which is one of the examples above.)

[touseefbsb]

@mrlacey

1. (not targetted towards a specific issue ) it is a suggestion for a nice to have which will promote better design accross all windows 10 devices and promote developers to publish more apps on all devices.

2. it should be applied to all pages ( but ofcourse as an optional feature in the wts wizard, because if the developer doesnt want this feature they can opt for normal uwp app without tailored design and deal with adaptive stuff themselves.

3. I don't think it would be so simple to add this feature to an existing project or existing pages, ofcourse its a possibility but I think it might be very complicated to do this.

4. Yes if a project is generated with this feature , and later on the developer adds another page to the project, then yes this feature should be applied to the new page added to that project as well.

5. yes the general way is to use one single page for all sizes, but here I am not just talking about responsive code with screen size changes. that will still happen on each page with Visual State Triggers and No I am not proposing bad practices because, I have seen **Kevin Gallow ** ( director of UWP development ) state it multiple times in windows community standup and other events, that no matter how much adaptive code you can write, he still recommends to write tailored code for each device, the reason to that is tailored design takes it beyond the screen size change, rather it also deals with device specific best practices, device specific APIs, and ultimately developer doesnt have to worry about if statements everywhere to check on every page about which device the app might be running on. that is why it should be an optional feature so only those who know what a tailored design is and if their app needs very different stuff for each device, only then they should use this feature. otherwise they can go with the usual. both of these approaches are best practice , it actually depends on the app being made.

6. yes project structure will be a bit different, but it wont be too different, the only thing which changes in this case are the views either all of them can be put into device specific folders within the View Folder, or they can use the name extension as MainPage.Desktop.xaml and so on, I think folder approach is better as this structure is more modular and easier to maintain. ( details are on the tailored design docs I provided before ) also multiple ViewModels can be provided as per device and page, but tht can be discused, and isnt tht hard bcz a ViewModel is just a simple class inheriting from Observable

7. Yes there are multiple ways to do that, but there are multiple ways to do everything in uwp, but wts usually provides the best possible way, we dont need to provide every posibble way to do this, as that would be too hard to implement, so one prefered way ( folder structure in my opinion ) would be good enough.

8. Right now yes most people just opt for Desktop and dont use other device families a lot, but bringing tailored design into WTS might actually promote developers to go for all devices because they dont have to find out wht they have to do for each device, bcz wts is already telling them wht to do with generated code and Comments Docs

9. for example, a xbox specific view will have code for ( remove pointer, tv safe colors, xy navigation recomendation, tv safe margins, use relatively larger text, use lesser UI elements on a page, handle a keydown and keyup event for all gamepad buttons and xbox remote control buttons) these are just the most basic things one has to do for even the most basic xbox app ) each device can have recommendations like these specific to their device family.

10. TODOs will be different for all device families, as I mentioned above the stuff needed for example for xbox, so some of that stuff will be present in form of generated code on that view, and some will be in TODO comments, with some commented code and some links to docs for further in depth details ( if needed ) the todos which we need for a xbox view does not apply for a desktop view and so on.

11. Yes testing can be a problem, but even if this feature doesnt exist, people still dont have all devices and the contribution and innovation for all devices still remains limited. but this feature can be atleast 1 step towards targeting more devices. I think hololens emulator does exist as a seperate installation. and about 90 percent of xbox functionality can be tested on a PC with a gamepad attached to the pc and the page simulating the xbox view on the pc for testing purposes.

and no I didn't know about the extension I'll have a look at it now :)

[touseefbsb]

the tool is good, it reduces friction and helps to add pages or folders with device specific naming, but it doesnt give the code or recomendations for each device in the generated code, but still it is a good starting point for tailored design

[mrlacey]

This feels like a very generic request for lots of broad advice in a wide range of scenarios with a view to helping developers produce better designs.
While I applaud the motivation behind such a request, this seems unrealistic and beyond the scope of what WTS aims to provide. We're not in a position to provide design advice and I doubt just adding links to existing documentation in the generated code will be very beneficial.

Having previously spoken with Kevin on several occasions about the subject of tailoring for different device types, my understanding of his intention (and the advice I'd give also) is that you should tailor the experience for each type of device it will run on. You can't expect that what works on one device will work on another. You should design for and test on all the environments where your app will run.
This does not mean that you must create a separate UI for each platform.
There is a balance to be found between the complexity of one UI that adapts to different platforms and the maintenance overhead of dealing with the duplication of identical or similar functionality in multiple places. There are no absolutes for which is best and personal preference will play a part in the decision. In terms of general advice, I suggest starting with a single UI that adapts and then switch to multiple files when the complexity becomes too great or you want the functionality to be very different.

The original intent behind this issue was to gather together links to relevant documentation because we can't provide templates that will account for all the customization that may be needed on a per-device basis.

If you have specific concrete examples of where templates can be extended to support common device specific accommodations we should look at those as separate issues.
This issue will remain about providing links to existing documentation.

[touseefbsb]

ok sure, just providing docs for each device customization is also a good move,

[mvegaca]

Doc added on #2341
@mrlacey if you think that I missed some link please communicate it to me or feel free to add it on the doc page.