Request for comments: Improving the Project_Readme.html

[sayedihashimi]

Today someone showed me a build keynote showing a cool workflow while working with Xamarin tutorials, here's a direct link to where it starts https://channel9.msdn.com/Events/Build/2016/KEY02#time=15m40s.

I'd like to see how we can apply similar thinking to the Project_Readme.html page that is displayed after project creation from the One ASP.NET dialog. Today it's a page with a bunch of links. It's a missed opportunity to help users interact with their project and to learn ASP.NET Core in a more meaningful way.

My goals of modifying this page and including some project interaction would include the following.

• Help the user understand their project and it's artifacts
• Help educate the user about ASP.NET Core (especially on the parts that are different from before)

For example, the Add Controller link could open open the scaffold dialog with Controller selected. Or the appsettings link could open the appSettings.json file, etc.

I'm putting this here in case community members want to propose ideas for how we can evolve this. I don't have any specific thoughts at this time so it's an open slate. If you have a proposal, the more specific you can be the easier it will be for me to understand that.

In the video linked above you can see that he edits the tutorial and then immediately runs the app with his changes. For our ASP.NET scenario I don't think it makes sense to do "direct editing" in the Project_Readme, but instead use it as a launch point to show users which specific files to edit/modify in their project

Here's a screenshot of the Project_Readme.html (aka "The Pranav Page")

[peterblazejewicz]

I think of README in a scaffolded templates as a default content, but optionally disabled feature of the scaffolding tool (here with VS IDE) that could serve as starting point for any newcomer to a given type of framework or project type. So for example I could think that MVC + EF project should have different starting points/hints/links for newcomers compared to console app template. I'd put different content for MVC project (hey, look, you could host this that way or another or use different DB) and different for console (hey, here is a cool way to use progress bars or argument parsers in similar, console app projects). Once newbee gets accustomed to framework, she can skip (via IDE option) creation of default README completely. I've been writing tech docs for software for some time and we used readmes a lot as a place for some most common hints to first time or not advanced users (*start here, do this, when you play with template try this and this, etc). Thanks!

[sayedihashimi]

So for example I could think that MVC + EF project should have different starting points/hints/links for newcomers compared to console app template.

I thought we had different versions of Project_Readme.html for the different templates. I will double check this.

@peterblazejewicz if I understand you correct, your OK with having a text/html file with links as long as the content is tuned to that particular template. How about trying to make the experience a bit more interactive?

[rschiefer]

I really like this idea! So many new developers struggle getting started and this could go a long way to help them.

Advanced developers could also use this functionality to create custom project readmes with their own extensions/interactions as well to increase productivity with their teams.

[peterblazejewicz]

I thought we had different versions of Project_Readme.html for the different templates. I will double check this.

No. The content is virtually the same. In the Yo generator we have added readme to console template, library template, etc. Project readme in templates are provided only for empty/webapi/web.

[peterblazejewicz]

@peterblazejewicz if I understand you correct, your OK with having a text/html file with links as long as the content is tuned to that particular template. Yes How about trying to make the experience a bit more interactive? This could be hard to be non-VS specific, but I clearly see the gains with interactive content (for all levels of VS users) Thanks!

[brockallen]

If they've gotten as far as creating a new ASP.NET project in VS, do they really need that file?

I have never read the contents of this file and always delete it as the first step in every new project I create because it's in my way. When I create a project I want to get my job done, so why pollute the project with an extraneous file.

Perhaps it'd be better to have a notification in VS somewhere (that can be disabled) for this project type so you can learn more (which allows for more up to date links). Perhaps even a NuGet help link tie-in? Let the user use their browser to learn, rather than have an embedded/static file in the project template.

[peterblazejewicz]

If they've gotten as far as creating a new ASP.NET project in VS, do they really need that file?

The readmes/howtos are for all people, especially starting with development. Otherwise people don't have teaching notes: http://nodeschool.io/ or this more established and older one: http://guides.rubyonrails.org/getting_started.html

[lucamorelli]

I think that first af all we must understand what we can actually do, considering that is a html page opened with the file protocol

[RehanSaeed]

One thing I've done in ASP.NET MVC Boilerplate is to create a check-list in the ReadMe.html file that gets generated as part of my project template to make it interactive.

I'm using Persis-JS to store when a user has checked a check-box and also to collapse or uncollapse expander sections. It puts the settings in local storage or if the user is using and older browser it uses other alternatives.

What you put in there is key! I created sections for security, performance, accessibility, SEO etc. and then provided tasks to help improve the site further. These are links and suggestions to help even the most advanced developer but newbies too.

To give it a try you can either create a project using the project template or take a look at the ReadMe.html file.

[aspnet-hello]

All issues in this repo are being closed because this repo is no longer in use. Please see the readme for more information: https://github.com/aspnet/Templates/blob/dev/README.md.