Project Name: Overhaul Fastify Docs Technical Writer: Light (Segun Olumide) Mentors: Matteo Collina, Tomas Della Vedova
The Goal of the project to create standard documentation for users by establishing a style guide that will be the foundation of fastify current documentation which will then be applied once the style guide is achieved.
- Creating Style guideline for Fastify
- Rewording the documentation to follow the style guide
- Glossary of terms
Documentation Title: Style Guide Github Repository link: https://github.com/fastify/fastify/blob/master/docs/Style-Guide.md Status: Merged Commits History/Pull-request: fastify/fastify#2574
Task Description: I set up a style guide for contributors to write standard documentations on fastify. The goal of the style guide is to make documentations easy for users to read and understand. The first step was to highlight what the guide is for and why it exists. Here are the following highlighted guidelines concluded:
Consider the Audience - The whole point of the documentation is for the audience and writing one without having your audience in mind will most likely lead to misinterpretation and might confuse the reader.
Get Straight to the Point - The writer should be able to make information brief and precise, without allowing the reader to take too much time trying to understand what it means.
Avoid using videos or image - Using videos/Images in documentation is not very efficient. Fastify framework keeps updating, and videos will tend to become outdated unless a new video is present, it is only allowed when writing an article or making a youtube video, providing a reference link to them.
Avoid Plagiarism - All documentations are to be original, and references should is to provided by the writer where necessary.
When to avoid and when to use the second-person pronoun "You" - This addresses the use of the second-person pronoun "You". It encourages the use of this pronoun in guides and articles and less of this in reference documentations.
Condescending terms - I highlighted specific words seems condescending to the reader, which might sound offensive or negatively challenge the reader level of understanding. [Reference: How to remove condescending language from documentation]
Grammatical moods - I explained when to use Imperative, Indicative and Subjunctive statements. Each statement has its use, knowing when to apply them can help the reader connect better with what the writer wants to pass across.
The use of active voice instead of passive - I explained how Active voice is a more compact and direct way of conveying your documentation.
How to name documentation titles - Here it is recommended that kebab-case and avoid the use of other case styles. [Reference: Case Styles].
How to use Hyperlinks - I explained the proper way of using hyperlinks and showed different use cases for them.
Below are the useful references used: Google Developer Documentation Style Guide Gatsby Style Guide Microsoft Style Guide
Documentation Title: Getting Started Guide Github Repository link: https://github.com/wonexo/fastify/blob/getting_started/docs/Getting-Started.md Status: In a pull-request draft Github branch: Getting-Started Commits History/Pull-request: fastify/fastify#2670
Task Description: I reworded the Getting Started documentation to follow the new guideline created in the style guide. Used a constructive approach to what Svelte have on their tutorial page just as recommended by my mentors. The goal was to make it easy for readers to learn how to use fastify from scratch by providing readers with a step by step example of how to use fastify framework and understand how they work. Here are the following documented steps :
Installing Framework (Installation) - How to install fastify framework on both mac windows and Linux operating system.
Require Framework to Listen for HTTP request - How to create a new server to listen for HTTP request.
Add a New Route - How to add a new Route to an application using async/await or callback method.
Getting Started Guide - Other topics are yet to be covered. It includes the following:
- Interaction with request lifecycle (Hooks)
- What are decorators and how to use them on Fastify
- How to add fastify plugin and how to use them
- Project structure which fastify follows
These are contributions I plan to complete even after this year's Season of Docs is over.
Glossary of Terms - This contains a list of term used in the documentation and their simple meaning in the context of the documentation.
At first, it took some time to get familiar with the installation of fastify which I needed to understand well, to improve the Getting Started Guide, I was able to resolve them from watching youtube videos from Matteo Cottolina and Golden Technology. Articles on Resolving node permissions, How to get up and running with fastify and Getting started with Express helped as well.