Docs: Incorrect examples

Created on 30 Aug 2019  Â·  7Comments  Â·  Source: dotnet/docs

This statement could be extremely confusing to new comers as it doesn't make sense in the context in which it is used: Logger.WriteMessage += LogToConsole;

It should be: Logger.WriteMessage += Logger.LogToConsole;

Also, In general these examples are confusing and lack essential information in both description and example content.


Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

Area - C# Guide Technology - C# Fundamentals P2 doc-bug up-for-grabs

All 7 comments

Thanks for adding this @SalFicara

We'll make sure to address this when we next update this document.

In the meantime, I've added the "up for grabs" label for any community members to address.

Actually, if you have a closer look to the full sample here, the line of code you pointed out is correct.

However I agree with you @SalFicara on the fact that the way it is explained in the article is quite confusing as we can't really understand where the LogToConsole method is located in the example program.

@BillWagner , based on the sample, it looks alright. Is this a bug or not?

@eddynaka

The previous comment is correct. The code is correct, but the explanation does not help readers find that information.

@BillWagner so should we change the code or explanation?

As the code is correct, we should rephrase the explanation only

I attempted to address this in two PRs across the docs & the samples.

  • I extracted to a static class called LoggingMethods so that we could show the full context of the class within the docs sample.
  • Updated the docs to show the new class for the contents of the LogToConsole method
  • Updated the docs to clearly use the static class
  • Added a comment to the first time we reference LoggingMethods out of context, to remind the reader it's one we created earlier.

Feedback on the overall approach welcome, but this seemed to find the sweet spot of:

  • Making a concept explicit
  • Allowing the code samples to be shown in the full context
  • Not being a huge departure from the existing sample
Was this page helpful?
0 / 5 - 0 ratings

Related issues

Manoj-Prabhakaran picture Manoj-Prabhakaran  Â·  3Comments

LJ9999 picture LJ9999  Â·  3Comments

ike86 picture ike86  Â·  3Comments

LJ9999 picture LJ9999  Â·  3Comments

garfbradaz picture garfbradaz  Â·  3Comments