🌇 Architecture & Paradigms

Documentation

For me, knowing how to build documentation is one of the rarest and most valuable skills among developers. This is also for me a critical point of non-hiring among junior candidates! Coming up with projects that have absolutely no documentation (markdown) is not acceptable in my opinion.

For a project on github for example:

• What are the prerequisites of the project? (version of Node.js, database used etc).
• What need does the project meet?
• Are diagrams available to better understand the architecture and the choices made in the project / code?

So remember to document your personal projects well because I think this has a very important impact for both technical and non-technical people (and I’m not talking about copying and pasting a getting started). Personally, I don’t need to see the code of a developer who builds documentation rigorously…

Example projects to inspire you: JS-X-Ray, SlimIO Config, Flydrive, Hooks.

Other resources, tools and packages to build documentations:

• JSDoc (voir aussi ESDoc).
• TypeDoc (pour TypeScript)
• Github Pages
• What it takes to build great product documentation
• Beyond the README: Creating Effective Documentation for Your Project by Rand McKinney, IBM

If you are building an API: having an OpenAPI with for example a Swagger interface can be a big plus (a postman collection can also do the trick).

---

⬅️ 🌇 Architecture & Paradigms: JSON Schema | ➡️ 🌇 Architecture & Paradigms: Clean Code