Create C# How to Section index by BillWagner · Pull Request #4031 · dotnet/docs

BillWagner · 2017-12-29T23:15:23Z

Over time, the existing How To articles will go in this section as they are updated for more common current scenarios.

In the meantime, the index provides a list of the existing How tos.

I have a few questions for @mairaw and @rpetrusha as I keep working on this:

Is there way too much LINQ content? There is a lot of LINQ to XML examples. Are those all still relevant?
I already removed the How to articles relating to reflection and CodeDom. Do you agree?

Internal review link

BillWagner · 2018-01-03T19:31:03Z

This is ready for a review @rpetrusha @mairaw

rpetrusha

I left a number of comments and suggestions, @BillWagner. I agree that the CodeDom articles can go. And I think that there is way too much LINQ content -- I suggested shortening the list to a few more simple topics per category, and eventually adding a LINQ how-to topics list in the LINQ docs. In terms of reflection, I'm somewhat mixed. But given that it's a purely framework and not a language topic, that seems to me to argue for its exclusion.

rpetrusha · 2018-01-04T00:05:43Z

docs/csharp/how-to/index.md

+
+# How to (C#)
+
+The How to section of the C# Guide is where you can find quick answers


Better: In the How to section of the C# Guide, you can find...

rpetrusha · 2018-01-04T00:06:44Z

docs/csharp/how-to/index.md

+# How to (C#)
+
+The How to section of the C# Guide is where you can find quick answers
+to common questions. There are cases on this page were one article may


In some cases, articles are listed in multiple sections on this page. We want...

rpetrusha · 2018-01-04T00:08:48Z

docs/csharp/how-to/index.md

+
+### Class and struct members
+
+You create classes and structs to implement your program. These techniques are common tasks when writing classes or structs.


techniques and tasks are different things. Maybe "These techniques are commonly used when writing..."

rpetrusha · 2018-01-04T00:10:44Z

docs/csharp/how-to/index.md

+- [Override the `ToString` method to provide string output](../programming-guide/classes-and-structs/how-to-override-the-tostring-method.md).
+- [Define abstract properties](../programming-guide/classes-and-structs/how-to-define-abstract-properties.md).
+- [Use the xml documentation features to document your code](../programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md).
+- [Explicitly implement interface members](../programming-guide/interfaces/how-to-explicitly-implement-interface-members.md) to keep your public interface more clear.


"more clear" seems like the wrong phrase. Perhaps just small? Or lean?

How about "concise"? I'd like to capture both size and clarity.

rpetrusha · 2018-01-04T00:18:36Z

docs/csharp/how-to/index.md

+- [Convert a string to a number](../programming-guide/types/how-to-convert-a-string-to-a-number.md).
+- [Use `as` and `is` to safely cast to a different type](../programming-guide/types/how-to-safely-cast-by-using-as-and-is-operators.md).
+- [Define conversion operators for `struct` types](../programming-guide/statements-expressions-operators/how-to-implement-user-defined-conversions-between-structs.md).
+- [Determine if a type is a nullable type](../programming-guide/nullable-types/how-to-identify-a-nullable-type.md).


or just "Determine if a type is nullable"?

I changed to nullable value type. I want to future-proof this against the upcoming non-nullable reference types. (The referenced article doesn't help determine nullable vs. non-nullable reference types, only value types.)

rpetrusha · 2018-01-04T00:25:18Z

docs/csharp/how-to/index.md

+- [Declare, instantiate, and use delegates](../programming-guide/delegates/how-to-declare-instantiate-and-use-a-delegate.md).
+- [Combine multicast delegates](../programming-guide/delegates/how-to-combine-delegates-multicast-delegates.md).
+
+Events provide a mechanism to publish notifications or subscribe to notifications.


publish notifications or subscribe to notifications --> publish or subscribe to notifications.

rpetrusha · 2018-01-04T00:27:12Z

docs/csharp/how-to/index.md

+
+Events provide a mechanism to publish notifications or subscribe to notifications.
+
+- [Subscribe and unsubscrbe from events](../programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md).


unsubscrbe --> unsubscribe

rpetrusha · 2018-01-04T00:31:44Z

docs/csharp/how-to/index.md

+Modern programs often use asynchronous operations. These articles will help you learn
+to use these techniques.
+
+- [Improve async performance using <xref:System.Threading.Tasks.Task.WhenAll%2A>](../programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md).


Links within a link don't resolve, so replace the xref with backticks.

rpetrusha · 2018-01-04T00:33:32Z

docs/csharp/how-to/index.md

+## Command line args to your program
+
+Typically, C# programs have command line arguments. These articles teach you to access and process
+those command line arguments.


Although both of the topics are about displaying command line arguments, I'd change the description here to retrieving them, which strikes me as a much more common operation than displaying them.

rpetrusha · 2018-01-04T00:35:55Z

docs/csharp/how-to/index.md

+- [Store event instances in a dictionary](../programming-guide/events/how-to-use-a-dictionary-to-store-event-instances.md).
+- [Implement custom event accessors](../programming-guide/events/how-to-implement-custom-event-accessors.md).
+
+## LINQ practices


Yes, there really is too much LINQ content; the LINQ section really overshadows everything else. Most are also not so much language topics as LINQ topics. I think that I would pare this down to a few of the more basic topics in each category, and possibly plan to create a more thorough list of LINQ how to topics in the LINQ docs later.

I pared it down to the first general How-tos. Those focus more on the query syntax, which is closer to the language.

BillWagner · 2018-01-04T21:12:37Z

@rpetrusha Thanks for the review. I updated this based on your feedback. In a couple spots I chose different wording than your proposed changes, and commented on those changes.

Let me know what you think on this round.

rpetrusha · 2018-01-05T17:19:04Z

I think that this looks really good, @BillWagner, especially the pared-down LINQ section. It's ready to merge when you're ready.

BillWagner and others added 5 commits December 20, 2017 13:46

initial checkin

cebb940

switching machines

bf9ede6

added find / grep output

7c84bd0

finixh 1st pass

d8c5e8d

update TOC and proofread

6a0e693

BillWagner changed the title ~~[WIP] Create C# How to Section index~~ Create C# How to Section index Jan 3, 2018

rpetrusha suggested changes Jan 4, 2018

View reviewed changes

BillWagner added 2 commits January 4, 2018 14:09

respond to feedback

2b9e440

pare the LINQ section.

9858e68

rpetrusha approved these changes Jan 5, 2018

View reviewed changes

BillWagner merged commit 04f4a04 into dotnet:master Jan 5, 2018

BillWagner deleted the csharp-how-to-section branch January 5, 2018 21:42


		# How to (C#)

		The How to section of the C# Guide is where you can find quick answers


		### Class and struct members

		You create classes and structs to implement your program. These techniques are common tasks when writing classes or structs.


		Events provide a mechanism to publish notifications or subscribe to notifications.

		- [Subscribe and unsubscrbe from events](../programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md).

Conversation

BillWagner commented Dec 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BillWagner commented Jan 3, 2018

Uh oh!

rpetrusha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BillWagner commented Jan 4, 2018

Uh oh!

rpetrusha commented Jan 5, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BillWagner commented Dec 29, 2017 •

edited

Loading