Skip to content

Commit

Permalink
Improving English translations & standardizing styles for various pag…
Browse files Browse the repository at this point in the history
…es (#19)

* docs: improving language of hello.md

* docs: improved English & styles on overview:intro

* docs: impoved language & styles of tutorials
  • Loading branch information
michaeljolley authored Aug 30, 2023
1 parent a065512 commit c4ca085
Show file tree
Hide file tree
Showing 4 changed files with 36 additions and 37 deletions.
21 changes: 10 additions & 11 deletions docs/hello.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,24 @@ sidebar_position: 0

# Hello, Dev

Thank you for embarking on this journey with us to create an ambitious and exciting developer experience that is continuously improving. 🎉🎉🎉
ExpressoTS strives to abstract away the complexities of software development to make it eaiser for you to build your next project. We want to make you more productive and help you focus on what matters the most, your business logic.

ExpressoTS is so simple yet efficient in getting the job done. We want to continue doing that, abstract all the complexities that the software development world brings and make it easy for you to build your next project.
If you think about it, every programming language feature or framework is built to accelerate the development process, but most fail to deliver good documentation, good developer experience, or to reduce the amount of boilerplate code you have to write. We want to change that.

If you think about it, every programming language feature, framework built, is to accelerate your development process, however we are continuously failing in delivering good documentation, good developer experience plus reducing the amount of boilerplate code you have to write. Everything should simply work!
> This is our commitment: to make your life easier, and to make you more productive.
This is our commitment, to make your life easier, and to make you more productive.
As a community-driven project, we want you to be part of this journey with us. Your feedback, ideas, and contributions will help us build a better developer experience for everyone.

We are very open to feedback, ideas, and contributions. We are a community-driven project, and we want to hear from you.

Thank you again for being part of this journey with us, Happy Coding! 🚀
Thanks for joining us in this challenge. Happy coding! 🚀

---

## How to read the doc
## How to Read this Documentation

- **[links](./overview/intro.md)**: All bold texts are links to other pages of the documentation or external links.
- `code`: Helps emphasize code snippets and commands, or key technical terms.
- **[links](./overview/intro.md)**: Bold text denotes a link to other pages of the documentation or external locations.
- `code`: Emphasized code snippets and commands, or key technical terms.
- Alerts: Are used to highlight important information.

:::note Used to express general information
:::
:::tip This is a tip
Expand All @@ -36,7 +35,7 @@ Thank you again for being part of this journey with us, Happy Coding! 🚀

---

## Support the project
## Support the Project

ExpressoTS is an MIT-licensed open source project. It's an independent project with ongoing development made possible thanks to your support. If you'd like to help, please consider:

Expand Down
28 changes: 14 additions & 14 deletions docs/overview/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@ sidebar_position: 0

# Introduction

ExpressoTS is a TypeScript lightweight framework for building scalable, readable and maintainable server-side applications.
The framework provides a level of abstraction on top of common HTTP server framework **[Express.js](https://expressjs.com/)** exposing their API's directly to the developer. This provides freedom and brings to the developer a tool that is well known and easy to use.
ExpressoTS is a lightweight framework for building scalable, readable and maintainable server-side applications in TypeScript.
The framework provides a level of abstraction on top of a common HTTP server framework **[Express.js](https://expressjs.com/)**, exposing their API's directly to the developer. This provides freedom and brings to the developer a tool that is well known and easy to use.

## Philosophy

ExpressoTS is a developer-friendly framework designed to streamline the process of building server-side applications. With a focus on readability, maintainability, and scalability, ExpressoTS aims to simplify the development process by providing a clear and concise structure.

Gone are the days of tedious setup tasks such as configuring logging systems, handling authentication, and connecting to databases. With ExpressoTS, developers can focus on what really matters - writing code. The framework takes care of the repetitive and time-consuming aspects of development, allowing developers to work more efficiently.

One of the key features of ExpressoTS is its flexible and extensible architecture. The framework provides a robust and powerful **[Dependency Injection](di.md)** system that enables developers to quickly and easily extend its functionality by creating and adding providers with their specific binding scope such as `Transient, Scoped, Singleton`. This allows developers to seamlessly integrate new features throughout the entire application without having to worry about the complexities of integration and coupling.
One of the key features of ExpressoTS is its flexible and extensible architecture. The framework provides a robust **[Dependency Injection](di.md)** system that enables developers to extend its functionality by creating and adding providers with their specific binding scope such as `Transient, Scoped, Singleton`. This allows developers to integrate new features throughout the application without having to worry about the complexities of integration and coupling.

Whether you're building a simple API or a complex enterprise application, ExpressoTS can help you deliver your project on time and on budget. With a comprehensive set of tools and features, ExpressoTS makes it easy to build high-quality, scalable, and maintainable server-side applications.

Expand All @@ -25,48 +25,48 @@ Before creating a project make sure you have ExpressoTS CLI installed globally o
npm i -g @expressots/cli
```

## Creating a new project
## Creating a New Project

To create a project using the CLI, simply run the following commands. The CLI will prompt you with a few questions and then create a new project directory with the name you provide, along with the @expressots/core package and a starter project structure.
To create a project using the CLI, run the following commands. The CLI will prompt you with a few questions and then create a new project directory with the name you provide, along with the @expressots/core package and a starter project structure.

```bash
expressots new <project-name>
```

Or you can create projects without going through the CLI questions by passing the template name (opinionated or non-opinionated) and the package manager (npm, yarn or pnpm) as arguments.
Or you can create projects without the CLI questions by passing the template name (`opinionated` or `non-opinionated`) and the package manager (`npm`, `yarn` or `pnpm`) as arguments.

```bash
expressots new <project-name> -t <template-name> -p <package-manager>
```

:::tip
ExpressoTS offers two starter project options: opinionated and non-opinionated.
ExpressoTS offers two starter project templates: `opinionated` and `non-opinionated`.

- Use the non-opinionated starter project when you need flexibility on your project structure.
- Choose the opinionated starter project for more complex projects with a complete starting point.
- Use the `non-opinionated` starter project template when you need flexibility on your project structure.
- Choose the `opinionated` starter project template for more complex projects with a complete starting point.
:::

### Accessing your project
### Accessing Your Project

After creating your project you can access it by running the following command:

```bash
cd <your-project-option>
cd <your-project-name>
```

### Executing in development mode
### Running in Development Mode

```bash
npm run dev
```

### Generating production build
### Generating a Production Build

```bash
npm run build
```

### Executing in production mode
### Running in Production Mode

```bash
npm run prod
Expand Down
12 changes: 6 additions & 6 deletions docs/tutorials/compression.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ sidebar_position: 1

# Compression

The npm compression package is a middleware that can compress response bodies for requests that traverse through it, which can help reduce the size of data that's sent over the network, leading to quicker response times and lower bandwidth usage. It uses the zlib library to perform gzip or deflate compression, both of which are widely supported by modern web browsers.
The npm compression package is a middleware that can compress response bodies for requests that traverse through it. This helps reduce the size of data that's sent over the network, leading to quicker response times and lower bandwidth usage. It uses the zlib library to perform gzip or deflate compression, both of which are widely supported by modern web browsers.

## Compression package
## Compression Package

- Performance: It can significantly reduce the size of the response body, thereby decreasing the time it takes for a client to download the response and render the content.

Expand All @@ -16,11 +16,11 @@ The npm compression package is a middleware that can compress response bodies fo

:::caution COMPRESSION OVERHEAD
This might not be ideal for high traffic websites where server resources are at a premium.
:::

Not all content benefits from compression. Binary files like images and videos are already compressed and trying to compress them further can sometimes even increase their size.
Not all content benefits from compression. Binary files like images and videos are already compressed and trying to compress them further can sometimes increase their size.
:::

## When to use
## When to Use

Deciding on when to use compression depends on the use case. If your website serves a lot of textual data (HTML, CSS, JS, JSON, XML etc.), then using the npm compression package can result in significant bandwidth savings and performance benefits. However, if your website is extremely high traffic, the additional computational overhead of compression might start to become a bottleneck.

Expand All @@ -38,7 +38,7 @@ Install the npm compression middleware.
npm i compression
```

After Installation you can add the middleware to your ExpressoTS app.
After installation, you can add the middleware to your ExpressoTS app.

```typescript
import compression from "compression";
Expand Down
12 changes: 6 additions & 6 deletions docs/tutorials/cookies.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,23 @@ Cookies can be used to support secure website functions. For example, a cookie c

It's also important to note that there are different types of cookies - session cookies, which expire when the browser session ends, and persistent cookies, which remain on the user's device for a set period of time or until they are explicitly deleted.

:::caution USING COOKIE FOR TRACKING
Have in mind that the use of cookies, especially for tracking and personalization, has raised privacy concerns, leading to regulations such as GDPR in Europe and CCPA in California that require sites to disclose their cookie usage and obtain user consent.
:::caution USING COOKIES FOR TRACKING
Keep in mind that the use of cookies, especially for tracking and personalization, has raised privacy concerns, leading to regulations such as GDPR in Europe and CCPA in California that require sites to disclose their cookie usage and obtain user consent.
:::

## Cookie-parser package
## Cookie-Parser Package

- Ease of Use: cookie-parser makes it very easy to read cookie values, which are often used for tracking user sessions, personalization, and managing stateful applications. Without this library, you would have to manually parse the Cookie header and handle the nuances of cookie formatting.

- Signed Cookies: The package also supports signed cookies, which are a way to verify the integrity of cookies (i.e., whether they have been tampered with). This is an important feature for securing sensitive information stored in cookies.

## What to consider when using cookie-parser
## What to Consider When Using cookie-parser

- Overhead: While it's not a heavy library, using cookie-parser does add a bit of overhead to each request, as it parses all cookies regardless of whether they are used in the route handler.

- Stateful: Cookies inherently make an application stateful. When scaling an application, state can be problematic. Therefore, alternative stateless authentication methods, like tokens, can be preferable in a microservices architecture.

## When to use
## When to Use

Deciding when to use cookie-parser largely depends on your application's needs. If your web application requires state management and you've chosen to do that via cookies, cookie-parser can make your life easier and your application more secure with signed cookies.

Expand All @@ -48,7 +48,7 @@ However, if your website has heavy traffic, the overhead might become a concern.
In case you're dealing with a high traffic website, consider alternatives like sessions stored in a database, JWTs, or tokens stored in HTTP headers. Also, using a load balancer to distribute traffic and session store modules to maintain session data across multiple servers can help to manage high traffic and stateful data.
:::

Just like before, the best approach often involves combining multiple techniques, tailored to your application's specific needs. Testing and monitoring your application under realistic conditions can help guide your decision-making process.
The best approach often involves combining multiple techniques, tailored to your application's specific needs. Testing and monitoring your application under realistic conditions can help guide your decision-making process.

## Use with ExpressoTS

Expand Down

0 comments on commit c4ca085

Please sign in to comment.