Règles ressources projets.md

Guidelines concernant les ressources et les projets.

---

1. Comprendre ce guide

Ce guide vous servira à écrire des ressources et des projets. Voici le sommaire :

• Comprendre ce guide
• Règles de compréhension
• Règles de formatage
• HTML
• Ressources
• Projets

1.1. Règles de compréhension

Comment être clair dans l'écriture de sa ressource / projet ? Voici un guide.

1.1.1. Pas de sous-entendu

La clarté est très importante. Laisser le doute empêche toute compréhension rapide, et est déconseillé.

1.1.2. Ne pas hésiter sur les exemples

Quand on apprend, prendre des exemples de la vraie vie est toujours bien vu, surtout quand on explique des notions complexes et que l'on les découvre à peine.

1.1.3. Retours à la ligne

Cela ne sert à rien de faire des retours à la ligne à chaque phrase. Inversement, il est inutile de faire les paragraphes que 10 lignes.

1.1.4. Aparté

Au courant de la ressource ou du projet, on aura envie des fois de faire une aparté. Cela peut être pour trois raisons :

• Erreur commune
• Bonne astuce
• Métaphore expliquée / culture gé

Pour ces apartés, qui doivent être mises en valeur, nous allons les mettre dans des cartes. Ainsi, les personnes qui vont les lire sauront que c'est à part et important.

1.1.4.1. Erreur type

Pour certains concepts, certaines erreurs reviennent fréquemment. L'exemple est le fameux heroku run rails db:migrate. Pour ces erreurs, il est recommandé d'avertir le moussaillon à ce sujet. Il n'est pas obligé de mentionner la réponse (surtout quand elle est trouvable facilement sur Google), mais bien d'expliquer pourquoi cette erreur est arrivée et comment éviter qu'elle arrive dans le futur.

Il est possible de voir plus bas le formatage d'un message d'une erreur type.

1.1.4.2. Bonne astuce / questions fréquentes

Des fois, il y a certaines astuces qui valent la peine la peine de faire une aparté (exemple: mettre le terminal en anglais) car il faut expliquer pourquoi cette astuce est importante.

Des fois, il arrive que les moussaillons peuvent se poser des questions sur un point précis. Mettre la question en aparté permet de lui donner l'importance qu'elle mérite.

Il est possible de voir plus bas le formatage d'un message d'une astuce.

1.1.4.3. Exemple métaphore, culture gé

Des fois, c'est important de bien prendre le temps d'expliquer un concept avec un exemple de la vraie vie (ex : expliquer Git avec la métaphore d'une photo de groupe). Ou bien un petit "fait amusant" qui fera briller le moussaillon lors de dîners (ex : rm rf). Pour ceci nous les mettrons dans une carte à part aussi.

Il est possible de voir plus bas le formatage d'un message d'une astuce.

1.1.5. Expliquer est mieux que balancer la solution

The Hacking Project est l'école de la débrouille, balancer les solutions sans expliquer quoi que ce soit n'est donc pas recommandé. Il faut donc veiller à essayer d'expliquer le pourquoi des lignes de code que l'on met en exemple.

Pour illustrer ceci, dire comment résoudre une erreur est bien moins intéressant que d'expliquer pourquoi l'erreur se produit : la personne aura une démarche plus proactive dans sa résolution et évitera d'avoir un côté assisté où chaque erreur n'est pas comprise.

1.2. HTML - Format

Les ressources et projets sont au format HTML, il faut les écrire dans ce format. Voici donc des balises importantes ainsi que leur règles à respecter :

1.2.1. Titres

Voici comment les titres sont ordonnés :

<h4>1. Introduction</h4>

<h4>2. Contenu</h4>
<h5>2.1. Première sous-partie du contenu</h5>
<p>Blabla</p>
<h6>2.1.1. Première sous-sous-partie du contenu</h6>
<p>Blabla</p>
<h6>2.1.2. Seconde sous-sous-partie du contenu</h6>
<p>Blabla</p>
<h5>2.2. Seconde sous-partie du contenu</h5>
<p>Blabla</p>
<h6>2.2.1. Première sous-sous-partie du contenu</h6>
<p>Blabla</p>
<h6>2.2.2. Seconde sous-sous-partie du contenu</h6>
<p>Blabla</p>

<h4>3. Points à retenir</h4>

Les balises commencent à <h4>, et les numérotation sont comme ci-haut.

1.2.2. Liens

Les liens ont le format suivant :

<a href="url" class="text-primary" target="_blank">clique ici pour le lien</a>

La classe text-primary permet aux liens d'avoir une couleur reconnaissable. Le target="_blank" ouvre les liens dans un nouvel onglet.

1.2.3. Bouts de code

Pour insérer des bouts de code, il faut faire :

<pre><code>array.each do |element|</code></pre>
  print "kikou"
end</code></pre>

Cela écrira :

array.each do |element|</code></pre>
  print "kikou"
end

Le code est dans une balise <code> qui est dans une balise <pre>. Attention, dans ces balises, chaque espace et retour à la ligne compte. Donc ne pas revenir à la ligne sur la première et dernière ligne de code, et commencer chaque ligne de code au début de la ligne (et non pas l'indentation actuelle du HTML).

Pour représenter une indentation, il faudra faire 2 espaces (4 espaces et le bout de code devient illisible.)

Enfin, voici la nomenclature pour réprésenter PRY et le terminal :

• PRY/IRB. Les lignes de ruby commencent par > , les lignes qui affichent le résultat commencent par => :

> print "ceci est une ligne de code ruby"
=> "ceci est une ligne de code ruby"

• Terminal. Les lignes de terminal commencent par $ :

$ git push origin master

1.2.4. Listes

Les listes sont classiques.

1.2.5. Images

Pour intéger une image, il faut un lien d'image permanent. Il faut comment par mettre l'image dans un service d'hébergement d'images, puis obtenir le lien direct en faisant Copier l'adresse de l'image, qui doit renvoyer sur une page qui a comme contenu que l'image.

Une fois que l'on a le lien, il faut le mettre dans une balise HTML :

<div class="imgwrapper">
   <img src="URL" class="img-responsive">
</div>

Avec ces balises, l'image sera adaptative.

1.2.6. Vidéos

On peut intégrer des vidéos, via le embed de Youtube. Il faut donc aller sur la vidéo, récupérer le code Embed (attention, l'URL embed est différente de l'url de la vidéo), puis le mettre au format suivant :

<div class="videoWrapper">
  <iframe width="100%" height="100%" src="https://www.youtube.com/embed/URL_DE_LA_VIDEO"  allowfullscreen></iframe>
</div>

Le div avec la classe videoWrapper s'occupe d'adapter la vidéo à la taille de l'écran de l'utilisateur.

1.2.7. Les cartes pour les messages d'aparté

Le template de base pour les cartes :

<div class="card">
  <div class="card-body">
    <h6 class="card-subtitle mb-2 text-CLASSE">TITRE</h6>
    CONTENU
  </div>
</div>

Le titre est :

• ⚠️ ALERTE ERREUR COMMUNE pour une erreur commune
• 🚀 ALERTE BONNE ASTUCE pour un bon plan astuce
• 🤓 QUESTION RÉCURRENTE pour une question récurrente
• 🎨 EXEMPLE ILLUSTRÉ pour un exemple illustré
• 📚 INSTANT CULTURE GÉ pour un instant culture gé

La classe est :

• danger pour une erreur commune
• info pour un bon plan astuce
• info pour une question récurrente
• success pour un exemple illustré
• success pour un instant culture gé

Pour le contenu, mettre ce que l'on veut. Il est possible de mettre des bouts de code avec <pre> et <code>.

2. Ressources

Dans cette partie, nous allons voir ce que nous attendons des ressources, et comment créer une bonne ressource.

2.1. Objectifs d'une ressource

Une ressource a un objectif principal : expliquer une notion précise

2.2. Architecture d'une bonne ressource

2.2.1. Introduction

Dans cette partie on va expliquer ce dont la ressource va parler et pourquoi on va en parler.

De plus, nous allons mettre une liste de questions auxquelles la personne qui lit la ressource sera capable de répondre.

2.2.2. Historique

Un peu de culture générale ne fait jamais de mal. Dans cette partie, en un paragraphe ou deux, nous allons parler de l’histoire de cette notion à travers l'informatique. Pour les tests ce sera long, pour le CRUD aussi (un peu d’histoire du web), pour la ressource sur le Seed, un peu moins long.

2.2.3. La ressource

Cette partie est le coeur de la ressource, elle va expliquer au format pas à pas. Dans cette partie nous évitons au maximum les liens (si une vidéo est super et explique bien la ressource, il faudra la retranscrire).

Les exemples de code ainsi que les erreurs courantes sont bien entendu de la partie. Et ne pas hésiter à faire des métaphores avec des exemples de la vraie vie.

2.2.4. Points importants à retenir

La partie précédente explique de manière exhaustive la ressource. Cette partie est le "récapitulatif à emporter avec soi". Quels sont les points importants à retenir ? Quel est le strict minimum de la ressource à garder pour la faire marcher ? C'est ici que cela se passe.

2.2.5. Pour aller plus loin

Dans cette partie, nous mettons les liens qui nous semblent intéressants pour approfondir la ressource. Pour chaque lien, il faudra mentionner la partie qui nous intéresse, ainsi la raison pourquoi on met le lien.

3. Projets

Dans cette partie, nous allons voir ce que nous attendons des projets, et comment créer un bon projet.

2.1. Objectifs d'un projet

Les projets sont le nerf de la guerre de The Hacking Project et principalement ce pourquoi les gens ressortent en sachant faire des choses.

Tout d'abord, un projet doit faire appliquer de manière concrète une ressource vue. Lire une leçon c'est bien, faire un pas à pas expliqué c'est bien, mais rien ne vaut une mise des mains dans le cambouis pour apprendre. Les projets servent à ceci.

Les projets ne sont pas guidés. C'est à dire on ne fait pas de choses comme "hey copie-colle ceci ici, bravo tu as une médaille pour avoir matté une vidéo". Aucun intérêt et l'on apprend pas. Un projet doit être stimulant intellectuellement et forcer la réflexion. Il faut qu'il soit dur, sans être décourageant.

Un projet doit être long. Les personnes qui veulent se dépasser pourront le faire. Et les personnes qui veulent rentrer chez elles à 18h pourront le faire aussi.

2.2. Architecture d'un bon projet

2.2.1. Introduction

Dans les grandes lignes, nous allons présenter le projet.

2.2.2. Le projet

Format 3 difficultés.

2.2.3. Rendu attendu

Ce que nous attendons comme rendu pour le projet.