Skip to content

update concept about.md explanation #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 3, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 47 additions & 19 deletions anatomy/tracks/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,45 +41,73 @@ concepts

### File: about.md

**Purpose:** Provide information about the concept for a student who has completed the corresponding concept exercise to learn from and refer back to.
**Purpose:** Provide more detailed information about the Concept for a student who has completed the corresponding Concept Exercise to learn from and refer back to.

**Presence:** Required

Once the student completes the exercise they will be shown this file, which should provide them with a summary of the concept. If the concept introduces new syntax, syntax samples should be included. At a minimum, this file should contain all information that is introduced in the exercise's [`.docs/introduction.md` document](./concept-exercises#filedocsintroductionmd).
After completing the corresponding Concept Exercise (otherwise known as "learning" a Concept), the Concept page will show the contents of the `about.md` file instead of the `introduction.md` file. The `about.md` file should provide students with comprehensive information on what they need to know to be fluent in the concept. At a minimum, this file should contain all information that is introduced in the Concepts' [`introduction.md` document](./concepts.md#file-introductionmd).

This document can also link to any additional resources that might be interesting to the student in the context of the exercise, such as:
If the Concept introduces new syntax, syntax samples should be included. The student should not have to follow a lot of links to gain the knowledge that the file tries to convey. Instead the `about.md` should contain enough information to be understandable within its context.

- Popular usages for a feature
- Common pitfalls in a feature's use (e.g. casual use of multiple **threads**)
The `about.md` file is not limited to the scope of the corresponding Concept Exercise. The content can require knowledge of other concepts that will be introduced later on. If other Concepts are mentioned, their respective introductions should be linked to (see [internal linking](https://github.com/exercism/docs/blob/main/anatomy/tracks/internal-linking.md) for details).

Here some examples of what could be covered.

- Popular usages for a Concept
- Common pitfalls in a Concept's use (e.g. failing to consider thread-safety)
- Limitations on use that may catch out the unsuspecting developer
- Alternative approaches addressed in other exercises
- Alternative approaches addressed in other Concepts (e.g. the ••recursion** Concept might reference that the **Higher Order Functions** Concept offers an alternative approach to similar problems)
- Compromises made for ease of learning or to accommodate the Exercism environment, e.g. multiple classes in single file
- Similar features with which the concept may be confused
- Performance characteristics and memory usage
- Similar features with which the Concept may be confused
- Performance characteristics and memory usage, when a common consideration within that language

It is **not** the aim of the `about.md` file to provide a complete set of information on the Concept. As an example, imagine a language that has some older features for which experienced programmers (and maybe even the official docs/specs) recommend they should not be used anymore. Providing details on such features would be out of scope for the `about.md` file because they are not relevant to gain fluency. However, maintainers may choose to add a short block to acknowledge the old standards if a student might commonly come across those standards in the wild. However, this block should be demarked as such.

The `about.md` file MUST be clearly structured, especially when it contains a lot of information. In the future there will also be support for marking parts as "advanced topics" to point them out to interested students without overloading others.

#### Example

````markdown
# About

One of the key aspects of working with numbers in C# is the distinction between [integers](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types) (numbers with no digits after the decimal separator) and [floating-point numbers](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types) (numbers with zero or more digits after the decimal separator).
There are two different kinds of numbers in Elixir - integers and floats.

The two most commonly used numeric types in C# are `int` (a 32-bit integer) and `double` (a 64-bit floating-point number).
Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

```csharp
int i = 123;
double d = 54.29;
```elixir
float = 3.45
# => 3.45
```

Both integers and floating-point numbers can use the `_` character as a _digit separator_, which can help when defining large numbers:
Elixir also supports the scientific notation for floats.

```csharp
int largeInt = 1_000_000;
// => 1000000
```elixir
1.25e-2
# => 0.0125
```

## Rounding errors

Floats are infamous for their rounding errors.

```elixir
0.1 + 0.2
# => 0.30000000000000004
```

However, those kind of errors are not specific to Elixir. They happen in all programming languages. This is because all data on our computers is stored and processed as binary code. In binary, only fractions whose denominator can be expressed as `2^n` (e.g. `1/4`, `3/8`, `5/16`) can be expressed exactly. Other fractions are expressed as estimations.

double largeDouble = 9_876_543.21;
// => 9876543.21
```elixir
# 3/4
Float.ratio(0.75)
# => {3, 4}

# 3/5
Float.ratio(0.6)
# => {5404319552844595, 9007199254740992}
```

You can learn more about this problem at [0.30000000000000004.com][0.30000000000000004.com]. The [Float Toy page][evanw.github.io-float-toy] has a nice, graphical explanation how a floating-point number's bits are converted to an actual floating-point value.
````

### File: introduction.md
Expand Down