/notes

Class docs, finally!

 

1 - Requirements

To develop these docs, you should be familiar with Markdown formatting language. You can read the documentation written by its creator John Gruber here, and if you need a refresher, this tutorial should suffice.
To write these docs, you can use MacDown (brew cask install macdown), an editing markdown software that allows you to see how your file is rendered.

Also, a suggestion would be to use this if you use Google Chrome, in order to be able to render your .md files the way you want them. You should also have access to the Trello board where we organize who's in charge of each document. Visit this to add yourself to the board.

 

1.1 - Git flow for doc development

As follows:

  1. Clone the repo or pull the latest changes
  2. Create a new branch matching the name in the directory structure for the doc you want to develop. (So, if I was trying to develop docs for code-conventions, that would be the name of the branch.)
  3. Edit the appropriate .md file
  4. Add, commit and push your changes to your branch
  5. Issue a merge request and assign the responsible person to it (Sérgio or Ferrão)
  6. Cross your fingers and hope to see your changes in the master soon

 

2 - Development

2.1 - Project structure

This project's structure is just a bunch of directories mimicking the structure we have on our slides. Each module has an index.md linking to all the docs for that particular module.

 

Each directory for a specific subject should have the same structure:

  • an md file, which is basically the doc file
  • a resources directory with two sub-directories (images and videos), where all the resources needed for that doc file should be
├── module-2
│   ├── code-conventions
│   │   └── code-conventions.md
│   ├── concurrent-programming
│   │   ├── concurrent-programming.md
│   │   └── resources
│   │       └── images
│   │           ├── crushdreams.png
│   │           ├── l1-l2-l3-cache.png
│   │           ├── lock.png
│   │           ├── multi-tasking-os.png
│   │           ├── pre-emptive-multitasking.png
│   │           └── single-core-cpu.png

 

2.2 - md file structure

  • Make sure to have a lot of links, so that when an mc is using the doc, they can click on them directly, instead of having to go look for it.

  • All the visual resources you need should be in the resources directory for that particular class. (this ensures we never have broken links, if a picture is removed from a certain server).

  • All links should be reference and not inline. If you need examples, use this README as a template. (this makes it easier to change them later).

    if you're trying to link to files in the resources folder, just wrap the path in <> to convert it to a link

  • Use headers appropriately, don't abuse them. Headers lives matter. No, but seriously, we usually use level 2 to identify slide number, and lower levels where appropriate. Using headers appropriately will make it easier to navigate through your doc file later.

  • Docs should be written using we/us instead of I/me/you, as that's how we should talk when giving a lecture. It's also a good idea to reference things that cadets have learned previously.

  • In order to enforce some styling, a .prettierrc file is included in this repository, please make sure to format all your files making proper use of it. (this is still subject to change)

 

Purpose

  • The idea is to have a somewhat organized and standard flow for all the classes given in the bootcamp, consistently accross campuses.

  • Not only that, these documents are meant to support master coders (especially new ones) when preparing lectures by providing better documentation and flow for any given class.

  • All of these files should start with a context section, to help contextualize the subject that we'll be talking about next.

  • Each doc must add extra information besides what's on the slides, have frequently asked questions by the cadets, show different code examples for hands-on demonstrations and contain pictures or drawings that can be used when explaining a new concept.

  • If you drew an awesome picture in class, make sure to take a picture and upload it to the resources for that class, so that people can later reference it.

  • Use and link to outside resources, be it videos, tools, pictures, diagrams, what have you!