repharse blog post

website/blog/2023-05-16-fast-check-loves-docusaurus/index.md

@@ -5,86 +5,89 @@ tags: [retrospective]
 image: ./social.png
 ---
 
-The story of fast-check's documentation: from markdown files accessible on the repository to a proper website available at [fast-check.dev](https://fast-check.dev/).
+The story of fast-check's documentation: from markdown files accessible in the repository to a proper website available at [fast-check.dev](https://fast-check.dev/).
 
 <!--truncate-->
 
 ## Story
 
-The idea to bootstrap a dedicated website for the project fast-check is not new. Let's dig into the various steps of our doucmentation: from the early days when fast-check was a niche project until now with a project reaching [close to 1 million monthly downloads according to npmjs](https://www.npmjs.com/package/fast-check).
+The concept of creating a dedicated website for the fast-check project has been on the radar since day one. In this section, we will dig into the different stages of our documentation journey, starting from the early days when fast-check was a niche project, all the way to its current state where it reaches [nearly 1 million monthly downloads on npmjs](<(https://www.npmjs.com/package/fast-check)>).
 
 ### Bring adoption
 
-When the project started bringing adoption was key. First users of fast-check were early-adopters of the project. At that time, the project was far from stable: no major version released, a dubious README file, releases broken from time to time… But it already fulfilled most of his targets: making property based testing simple and accessible to everyone.
+When fast-check started, gaining adoption was key and it passed by attracting early adopters to the project. These initial users were willing to embrace the project despite its unstable nature: lack of major releases, a questionable README file, and occasional broken releases. But they adopt it as fast-check already fulfilled its primary objective: make property-based testing accessible to everyone.
 
-So in order to bring confidence in the project, we worked onto polishing its external shape. It passed by shaping a proper README file, stopping to break releases and providing a showcase site. While it can seems stupid, the showcase site was able to give some confidence into the project and bring more early adopters to start using it.
+To bring confidence in the project, we focused on refining the appearance of the project. It involved improving the README file, ensuring stable releases, and creating a showcase site. Although seemingly insignificant, the showcase site played a vital role in inspiring confidence and attracting more early adopters in the early days.
 
-At that time, the project was alone in the repository and I had neither tooling ready nor the knowledge to setup workspaces to build it along a website for it. So everything started with two distinct repositories:
+At that time, the project was a standalone repository without any workspaces or monorepo architecture. Consequently, we built the showcase in a seperate repository:
 
-- one responsible to hold the project itself,
-- another for the showcase website.
+- One repository for fast-check project itself,
+- Another repository for the showcase website.
 
-Our initial showcase site was restricted to a single static page deployed as a [GitHub page](https://pages.github.com/) and based on [Jekyll's templates](https://jekyllrb.com/docs/). It was nothing more than a showcase listing key characteristics of fast-check and showing one example of test written with it.
+Our initial showcase site consisted of a single static page deployed as a [GitHub page](https://pages.github.com/) and relied on [Jekyll's templates](https://jekyllrb.com/docs/). Its purpose was to showcase the key features of fast-check and demonstrate a sample test written using the library.
 
 ### Keep users
 
-After the first early adopters, we needed to preserve users and continue growing our set of users. We wanted to make fast-check known to many JavaScript developers to help them in their everyday job by providing them with tools able to help them into finding bugs.
+After attracting early adopters, our focus shifted to retaining them. We also continued to expand our user base and aimed to introduce fast-check to a wider audience of JavaScript developers, enabling them to leverage its powerful bug-finding capabilities in their daily work.
 
-But to keep users, we needed to have a clear and accessible website with the documentation of our APIs. At that time, all of them were fully documentated via [JSDoc](https://jsdoc.app/) so we looked into tools able to convert these annotations into a website. We experimented several solutions and landed onto [typedoc](https://typedoc.org/).
+To achieve this, we recognized the having a clear and accessible website that provided comprehensive API documentation was required. At that time, all our APIs were fully documented using [JSDoc](https://jsdoc.app/). Therefore, we looked for tools that could convert these annotations into a user-friendly website. Through experimentation, we eventually settled on [typedoc](https://typedoc.org/).
 
-This new layer of documentation helped us into drastically dropping the number of GitHub issues related to questions asking if there was an API for such or such operation. With that new layer, users were able to autonomously find the relevant APIs.
+This new layer of documentation proved key in reducing the number of GitHub issues related to questions about specific APIs. With this enhanced documentation, users were empowered to independently locate the relevant APIs, promoting self-sufficiency and streamlining the support process.
+
+Overall, these efforts enabled us to not only retain existing users but also attract new users who sought reliable and well-documented tools for their production needs.
 
 ### Grow adoption again
 
-But as users started to like the framework, they started to spread it in their communities and to ask for new features. Among these new features some started to be already there and more and more feature requests ended to be either already implemented or out-of-scope. But there was no easy way for users to find such information.
+As users began to embrace the fast-check, they shared it within their communities and expressed their desire for new features. Interestingly, some of these features were already implemented or just felt outside the project's scope. However, there was no convenient way for users to access this information.
+
+What was lacking was a real documentation layer. Given the success of the previous layers and the absence of a proper monorepo structure at that time, we opted to start with a set of dedicated markdown pages. These markdown pages served as the foundation for our initial standalone documentation.
 
-What was missing was a real documentation layer. As everything was working for the two previous layers and because we were still in a non-workspaces world, we decided to start with a few set of markdown pages. These markdown pages allowed us to come up with a first real documentation fully outside of the code.
+This approach allowed us to address the growing needs of our user base and provided a resource where users could find valuable information about the framework, including the state of existing features and ways to use them. By establishing a dedicated documentation layer, we aimed to enhance user experience, facilitate feature discovery, and foster better communication between the project and its users.
 
 ### Limitations
 
-While we kept it many years, the approach had several limitations.
+While we preserved the setup for several years, it eventually revealed certain limitations.
 
-Our showcase website was hard to maintain and we often forgot about it. We got pinged many times by users because of dead links in this showcase.
+Firstly, maintaining our showcase website became challenging. It was rarely kept up-to-date and suffered from dead links being spotted by users from time to time.
 
-Our markdown version was great but not as flexible as we wanted. We were not able to keep it on-par with other modern documentations. It lacks of many things including:
+While the markdown version of our documentation served its purpose, it lacked the desired flexibility. It fell short in comparison to modern documentation standards, lacking key features such as easy browsing, searchability, customizable styling options, and the ability to integrate analytics.
 
-- Not easily browseable,
-- Not easily searchable,
-- No way to apply custom style to it,
-- No way to plug analytics.
+Moreover, users often felt overwhelmed and confused by the presence of three separate documentation sources, each accessible through different URLs. This fragmentation further complicated their journey in finding the information they needed.
 
-Finally the users were a bit lost into all these documentations. There was not one but three of them, each available at different URLs.
+Recognizing these limitations, it became clear that a more cohesive and robust documentation solution was necessary.
 
 ## New version
 
-While bringing adoptions and preserving users is still key to the project, this new iteration mostly focused on making the documentation easily browseable and above all easy to maintain. The maintainance cost of a documentation is probably one of the less known part of open-source but it's damn important and the easier it is to document things the better for the project.
+While attracting and retaining users remains crucial, this iteration primarily attempted to enhance the accessibility and easesimplicity to maintain our documentation. Indeed, an often overlooked aspect of open-source projects is the significant maintenance cost associated with documentation. Simplifying the process of documenting aspects of the project is important, as it directly impacts the project's overall success and growth.
 
 ### Inspirations
 
-Before we jumped onto one solution or another, we started to look at the current state of the art of documentations. I personally was astonish by [svelte's one](https://svelte.dev/tutorial/basics) when I played with it for the first time. The hand's on part was mind blown. At that time, I built a rather dummy adaptation of a hand's on tutorial as a markdown page.
+Before diving into specific solutions, we first examined the current state-of-the-art of documentation practices. Personally, I was amazed when I came across the documentation for [Svelte](https://svelte.dev/tutorial/basics) and had the opportunity to interact with it. The interactive and hands-on nature of the tutorial left a lasting impression. Inspired by this experience, I created a basic adaptation of a hands-on tutorial using markdown pages only.
+
+Documentations started incorporating interactive elements, enabling users to experiment and code within the browser itself. This approach revolutionized the learning experience, empowering users to engage with the technology more effectively without needing to go outside of the browser. The new documentation of [react](https://react.dev/learn) is a great example of such switch.
 
-Then came documentations of [react](https://react.dev/learn) and many others. They more or less started to offer in documentation hand's on where the users can play directly without living the browser.
+So we needed to make something!
 
 ### Docusaurus
 
-After several months wondering when I would finally take the time to migrate to a proper documentation system, I finally started to POC something based on [Docusaurus](https://docusaurus.io/). The tool being there for some years now and used by many huge projects including [Jest](https://jestjs.io/), [Redux](https://redux.js.org/) and others, I wanted to be part of them too.
+After several months wondering when to take the time to transition to a proper documentation system, I finally began a proof of concept based on [Docusaurus](https://docusaurus.io/). The tool has been around for some years and is used by major projects like [Jest](https://jestjs.io/), [Redux](https://redux.js.org/), and others. I wanted to join the movement too.
 
-I really liked the approach proposed by it:
+What first attracted me to Docusaurus was:
 
 - Every page can be a simple markdown file,
 - But you can switch to complex React code whenever you want spicy logics.
 
-I also enjoyed the fact, that many things come out-of-the-box for you:
+But behind the scene what makes it so powerful is rather how simple it is to use for documentations or blogs. It provides so many must-have things out-of-the-box:
 
-- Generating sitemaps,
-- Generating sidenav, table of contents…,
-- Checking for dead links,
-- Compiling the site for GitHub pages,
-- Handling routing.
+- Sitemaps generation,
+- Sidenav and table of contents generation,
+- Dead links detection,
+- Compilation of the site for GitHub pages,
+- Routing…
 
-While they might sound simple, they all come with a price and having them setup for you make launching a documentation website way simpler. These out-of-the-box features are ceratinly the ones that make the project so incredible when starting a documentation as you don't have to bother about routing, reading from markdown and compiling anything: all choices have been made for you while still giving you many level of freedom.
+Each comes with its set of complexities so having them preconfigured significantly simplifies the process of launching a documentation website. With Docusaurus, there is no need to concern yourself with routing, markdown reading, or any other common choice. They have been thoughtfully made for you, while still providing ample flexibility to tailor the documentation to your specific needs.
 
-And among all the crazy capabilities, I'm happy to finally be able to offer live playgrounds directly in my documentation! It makes me able to offer tutorials asking the particiapations of users like [this one on race conditions](/tutorials/detect-race-conditions/).
+And among all the exciting capabilities, I'm happy to be able to offer live playgrounds directly in the documentation. It makes us able to offer tutorials offering users with the ability to directly try the framework without leaving the documentation. You can experiment this new experience on [this tutorial about detection of race conditions](/tutorials/detect-race-conditions/).
 
 ### Recommendations