search

microsoft / TemplateStudio

Template Studio accelerates the creation of new WinUI 3, WPF, and UWP apps using a wizard-based experience.
Other
2.7k stars 460 forks source link

Review documentation #2294

Closed mrlacey closed 5 years ago

mrlacey commented 6 years ago

MEETING NOTES *Work out what docs should be on docs.microsoft VS GitHub

  • Research plan to moving to docs.ms (talk to community toolkit team)
    • How do we validate docs that are out of date?
    • Audit samples and see which can be moved to just documentation
    • Proof of Concept code & docs should never be in dev/master but stay in separate forks/branches

Action: Review the above meeting notes and raise separate issues as necessary.

scottkuhl commented 5 years ago

I just spent a couple of hours making a first pass at the documentation to see where it stands today. In my opinion a much better table of contents is needed as I was jumping around a lot. It should come close to mirroring the way project launch is organized.

There is some good documentation but it all needs thoroughly reviewed.

Moving forward, the documentation should ideally be reviewed as part of the pull request, but could be done as part of the release announcement / notes.

Getting Started seems comprised of readme.md, getting-started-extensions.md, getting-started-endusers.md, newitem.md, WTSNaming.md and templates.md

UI Services includes activation.md, navigation.md and navigation-advanced.md.

Project Types:

Design Patterns:

Pages

Features / Analytics

Features / Application Launching

Features / Application Lifecycle

Features / Background Work

Features / Connected Experiences

Features / User Interation

Services / Data

Services / Identity

Services / Tools

Testing

Miscellaneous documentation that did not seem to fit anywhere else includes platform-specific-recommendations.md, roadmap.md, updatetomultiproject.md, projectTypes/updatetonavigationview.md, projectTypes/updatetowinuinavigationview.md, and projectTypes/updatetohorizontalnavview.md

And finally a contributing section with getting-started-developers.md, issue_template.md, PULL_REQUEST_TEMPLATE.md, accessibility.md and telemetryData.md

scottkuhl commented 5 years ago

@mrlacey I know its been a long time but did you ever find answers to these questions:

mrlacey commented 5 years ago

@scottkuhl Short answer is that there has been no progress on this. (This issue was created at the same time as a lot of others as the result of a big planning meeting and progress on documentation seems to have got lost in the backlog.)

Improving documentation is definitely something that's worth doing but there's a lot to consider. (a quick brain dump follows)

There are also two very different audiences for the documentation.

  1. People working on the WinTS code base.
  2. People working with the code generated by WinTS.

These two will want and need access to different information.

Ideally, people using the wizard and generated code base should not have to come to the GitHub repository. (It's really only if they find bugs, or have suggestions for new features or improvements that they should need to come here.)

Where there is a potential need for them to know something specific about the generated code, that code includes comments that have a link to the relevant doc. Beware moving any existing documentation file that has a link in the generated code. (We don't want to break existing links if we can help it and there isn't a way to have automatic 301 responses returned by the repo.)

I'm not sure why you think that there should be a documentation file for every option in the wizard (my assumption based on all the things you've said are "missing".)

All wizard items already include some information that is accessible in the wizard. image

For some of the detail pages it might also be useful to add a link to a relevant GitHub docs pages too. Some detail pages already have this for external docs: image Adding links here seems like a sensible option.

I don't think it is worth duplicating the details available in the wizard in docs as well because we're not expecting people to come here to read them.

Documentation that is meant only for people working on the WinTS code-base or authoring templates makes sense to be here in the repo. I don't see a benefit in moving this to docs.ms.

While there may be an argument for moving details relating to generated code to docs.ms, there isn't much of it and it's already linked to the GitHub location. If I recall correctly, moving documentation to docs.ms was suggested as a nice-to-have. The general guidelines used when authoring templates is to try and minimize the need for writing custom, additional documentation and focus on including comments in the code that point to existing, official documentation instead.

Out of date docs is something that I think can only be tracked manually. Originally this was considered mostly in relation to samples as part of the docs but samples are not something that are being created within the main repository any more.

scottkuhl commented 5 years ago

@mrlacey Thanks for the detailed response.

Just so you know where I am coming from. I teach at a bootcamp for new students and many of the C# students end up drawn to Windows Template Studio. It's a great way to start building Windows apps. These students live and breath on Stack Overflow and GitHub. Plus when you search for Windows Template Studio there is a good chance you end up here.

So they definitely fall in the category, "People working with the code generated by WinTS.". What we have found is the documentation here sometimes goes deeper, sometimes is out of date, and sometimes is missing.

I think "consistency" is the real issue. "I'm not sure why you think that there should be a documentation file for every option in the wizard (my assumption based on all the things you've said are "missing".)" That has the appearance of incomplete.

Anyway, if I spot actual errors in the documentation I will open issues and try to fix them.

If there is any direction you would like to take the documentation and decide to open issues for it, I would be happy to help.

mrlacey commented 5 years ago

I'm going to update the docs detailed above in combination with #3284 #3285 #3286 and #3287

Adding placeholders for all items based on the description files used in the wizard. These can serve as future locations for potentially adding more details in the future.

Will aim to not break any existing links but will add in-place redirects if necessary.

mrlacey commented 5 years ago

Refactoring the grouping of documentation and basing the links at the bottom of docs pages on this too.

mrlacey commented 5 years ago

I've done a review of all documentation, updating references, filling in gaps, adding placeholders for everything, and checking links.

This doesn't mean everything is now perfect but this is hopefully a step in the right direction.

If you find anything that's wrong, missing, or out of date, please raise an issue with details or feel free to create a PR with a fix/correction/update yourself.

Going forward, we'll also add a step in each release to review documentation and ensure it is up to date. We're also looking at the possibility of an external review of documentation.