SurviveJS writing guidelines.
✅ Linted rules.
Chapters should be structured like this:
- Introduction
- Section 1 ... N
- Conclusion
The introduction should explain the topic on a high level and motivate the reader to dive in. It should be quite short, a few paragraphs at most.
The sections should discuss the given topic from different angles using illustrations whenever it makes sense.
The conclusion should recap the main points. This can be done as bullet points. It should also point to the next chapter so the reader knows what to expect there.
The ideal chapter length is between thousand and two thousand words. Sometimes a chapter can be shorter than this. If it's more than the upper bound, consider splitting.
Each book part should be a thematic unit. It should work as a presentation itself as the book material will be used for presentations and workshops later on. The feedback generated by those evolves the books.
Use italic to refer to other chapters of the book. This way the tooling is able to generate links to them automatically.
If some additional information is in some other book, refer there using a Markdown link.
To keep the writing closer to the reader, it's fine to use words like “we” or “I” and “you”. This way the text feels more personal. Use “we” or “I” to refer to the authors or the author and “you” to refer to the reader.
Prefer an official site, then an npm package page.
- Always capitalize the first word, even if it’s a stopword.
- Always capitalize the last word, even if it’s a stopword.
- Lowercase these words: a an and at but by for in nor of on or so the to up yet.