apache · joyqi · Oct 31, 2022 · Oct 29, 2022 · Oct 29, 2022 · Oct 29, 2022
diff --git a/docs/01-introduction/01-introduction.md b/docs/01-introduction/01-introduction.md
@@ -23,7 +23,7 @@ Main features:
 
 ## Architecture
 
-### Sperating the frontend and backend
+### Seperating the frontend and backend
 
 Answer is a monorepo that contains both the frontend and the backend.
 

diff --git a/docs/02-quickstart/02-quickstart.md b/docs/02-quickstart/02-quickstart.md
@@ -5,7 +5,7 @@
 
 :::tip
 
-We highly recommend that you use docker-compose to quickly get started with this application
+We highly recommend that you use docker-compose to quickly get started with this application.
 
 :::
 
@@ -19,14 +19,14 @@ $ docker-compose up
 
 :::note
 
-Different devices have different startup times, please wait patiently for the application to start.
+Different devices have different startup times. Please wait patiently for the application to start.
 
 :::
 
 ## Usage
 
-browser open URL [http://127.0.0.1:9080/](http://127.0.0.1:9080/). You can see the webpage as shown below.
+Open browser to the URL [http://127.0.0.1:9080/](http://127.0.0.1:9080/), where you should see the webpage shown below.
 
 ![login](/img/login.png)
 
-You can log in with the default administrator username( **`admin@admin.com`** ) and password( **`admin`** ).
+You can log in with the default administrator username (**`admin@admin.com`**) and password (**`admin`**).
diff --git a/docs/03-Installation/01-docker-compose.md b/docs/03-Installation/01-docker-compose.md
@@ -44,6 +44,6 @@ $ docker-compose up
 
 ## Precautions
 - After docker-compose startup, the data directory will be created in the folder to save the necessary data.
-- In docker-compose, answer use port `9080` and db use port `13306`. You can modify it if necessary.
-- We set `depends_on` in docker-compose, answer application will be started after db started. So it will teke some time.
-- We use docker-compose version is 3.9, So you may need to adjust according to your situation.
+- In that docker-compose, note that Answer is configured to respond on (publish) port `9080` while the db responds on (publishes) port `13306`. You can modify these as necessary (and it's not necessary to even expose/publish the db, if you don't want to access it from outside the container).
+- And due to the `depends_on` element, the Answer application ("answer" service) will not be available until the "db" service has started, which may take some extra time.
+- We use docker-compose version is 3.9, So you may need to adjust according to your situation.
diff --git a/docs/03-Installation/02-docker.md b/docs/03-Installation/02-docker.md
@@ -5,16 +5,16 @@
 
 :::tip
 
-If you want to install with docker, you need a database environment, such as mysql.
+If you want to run Answer via the docker command line, you need to have enabled and configure a database environment, such as mysql or mariadb. (Note that the [docker compose example](../Installation/docker-compose) shows integration of a database along with the Answer application.
 
 :::
 
 
 ## Docker for Answer
-> Visit Docker Hub or GitHub Container registry to see all available images and tags.
+> Visit [Docker Hub](https://hub.docker.com/r/answerdev/answer) or GitHub Container registry to see all available Answer images and tags.
 
 ### Usage
-To keep your data out of Docker container, we do a volume (/var/data -> /data) here, and you can change it based on your situation.
+To persist your data beyond the life of the Docker container, we use a volume (/var/data -> /data) here. You can modify the configuration based on your situation.
 
 ```bash
 # Pull image from Docker Hub.
@@ -40,5 +40,5 @@ $ docker start answer
 ```
 
 ### Notice
-- The first startup will report an error and fail, which is normal because the necessary configuration files are missing. It doesn't matter, the first startup will automatically initialize the required files for you.
-- For configuration file related fields, please refer to [config-file](../Usage/configfile)
+- The first startup will report an error and fail, which is normal because the necessary configuration files are missing. This can be ignored, as the first startup will automatically initialize the required files for you.
+- For more on the fields in the configuration file, please refer to [config-file](../Usage/configfile)
diff --git a/docs/05-Usage/04-database.md b/docs/05-Usage/04-database.md
@@ -4,7 +4,7 @@
 # Database description
 :::note
 
-Different databas have different data type. The following table uses mysql as an example.
+Different databases have different data types. The following table presumes use of mysql/mariadb as an example.
 
 :::
 

diff --git a/docs/07-roadmap/07-roadmap.md b/docs/07-roadmap/07-roadmap.md
@@ -5,7 +5,7 @@
 ## 2022
 | Feature             | Develop | Test | Release | Note               |
 | ------------------- | ------- | ---- | ------- | ------------------ |
-| Support PQ database | Q4      | Q4   | Q4      | support PostgreSQL |
+| Support Pg database | Q4      | Q4   | Q4      | support PostgreSQL |
 
 ## 2023
 | Feature | Develop | Test | Release | Note                       |

diff --git a/docs/08-FAQ/08-FAQ.md b/docs/08-FAQ/08-FAQ.md
@@ -4,13 +4,13 @@
 # FAQ
 ## How do I log in for the first time?
 
-You can log in with the default administrator username( **`admin@admin.com`** ) and password( **`admin`** ).
+You can log in with the default administrator username (**`admin@admin.com`**) and password  **`admin`**).
 
 ## Why can't I receive the registration email?
 
-You should config you own smtp address in admin setting interface.
+You should configure you own smtp address in the admin setting interface.
 
 ## How do I switch the default language?
 
-- Admin can switch the default language in admin setting interface.
-- Users can switch languages in their own settings interface.
+- Admin can switch the default language in the admin setting interface.
+- Users can switch languages in their own settings interface.
diff --git a/docs/09-Contributing/01-contributing.md b/docs/09-Contributing/01-contributing.md
@@ -2,10 +2,10 @@
 ---
 
 # Contributing
-> Thanks for the interest in contributing to Answer!
+> Thanks for your interest in contributing to Answer!
 
 ## How to Contribute
-> You can contribute directly to github by submitting your PR.
+> You can contribute directly to the github repo by submitting your PR.
 
 ## Creating an Issue
 - Feel free to ask your questions if you have any.
@@ -32,7 +32,7 @@
 The scope can be anything specifying place of the commit change.
 
 ### subject
-The subject contains succinct description of the change:
+The subject contains a succinct description of the change:
 
 - use the imperative, present tense: "change" not "changed" nor "changes"
 - do not capitalize first letter

diff --git a/docs/09-Contributing/02-frontend.md b/docs/09-Contributing/02-frontend.md
@@ -7,7 +7,7 @@
 - [Node.js](https://nodejs.org/) `>=16.17`
 - [pnpm](https://pnpm.io/) `>=7`
 
-pnpm is required by building the Answer project. To installing the pnpm tools with below commands:
+[pnpm](https://pnpm.io/) is required for building the Answer project. Install the pnpm tools with below commands:
 
 ```bash
 corepack enable
@@ -22,7 +22,7 @@ corepack prepare pnpm@latest --activate
 
 ## 🔨 Development
 
-clone the repo locally and run following command in your terminal:
+Clone the repo locally and run following commands in your terminal:
 
 ```shell
 $ git clone git@github.com:answerdev/answer.git answer
@@ -31,12 +31,11 @@ $ pnpm install
 $ pnpm run start
 ```
 
-now, your browser should already open automatically, and autoload `http://localhost:3000`.
-you can also manually visit it.
+Your browser should open automatically, and autoload `http://localhost:3000`. Or visit that URL.
 
 ## 👷 Workflow
 
-when cloning repo, and run `pnpm install` to init dependencies. you can use project commands below:
+When cloning repo, and run `pnpm install` to init dependencies. You can use the commands below:
 
 - `pnpm run start` run Answer web locally.
 - `pnpm run build:dev` build code for environment `dev`
@@ -51,12 +50,14 @@ when cloning repo, and run `pnpm install` to init dependencies. you can use proj
 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | last 2 versions                                                                                                                                                                                          | last 2 versions                                                                                                                                                                                                  | last 2 versions                                                                                                                                                                                              | last 2 versions                                                                                                                                                                                              |
 
-## Build with
+## Built with
+
+The Answer application is built using the following components/libraries:
 
 - [React.js](https://reactjs.org/) - Our front end is a React.js app.
 - [Bootstrap](https://getbootstrap.com/) - UI library.
 - [React Bootstrap](https://react-bootstrap.github.io/) - UI Library(rebuilt for React.)
 - [axios](https://github.com/axios/axios) - Request library
 - [SWR](https://swr.bootcss.com/) - Request library
 - [react-i18next](https://react.i18next.com/) - International library
-- [zustand](https://github.com/pmndrs/zustand) - State-management library
+- [zustand](https://github.com/pmndrs/zustand) - State-management library
diff --git a/docs/09-Contributing/03-backend.md b/docs/09-Contributing/03-backend.md
@@ -9,15 +9,15 @@
 ## 🔨 Development
 ### wire
 
-we use `wire` to generate dependencies.
+We use `wire` to generate dependencies.
 
 ```shell
 $ go get github.com/google/wire/cmd/wire@latest
 $ go generate ./...
 $ go mod tidy
 ```
 
-or you can use `make generate`.
+Or you can use `make generate`.
 
 ### swag
 
@@ -27,7 +27,7 @@ We use `swag` to generate swagger doc.
 $ swag init --generalInfo ./cmd/answer/main.go
 ```
 
-or you can use enter script directory and use `./gen-api.sh`
+Or you can use enter script directory and use `./gen-api.sh`
 
 ## 🏃🏻‍♀️ Run
 ```shell
@@ -43,11 +43,13 @@ $ vim ./answer-data/conf/config.yaml
 $ ./answer run -c ./answer-data/conf/config.yaml
 ```
 
-## Build with
+## Built with
+
+The Answer application's backend is built with the following components/libraries:
 
 - [pacman](https://github.com/segmentfault/pacman) - Yet Another Toolkit to Build Golang Application Quickly.
 - [gin](https://github.com/gin-gonic/gin/) - Router.
 - [validator](https://github.com/go-playground/validator/) - Validator.
 - [xorm](https://xorm.io/) - ORM.
 - [cobra](https://github.com/spf13/cobra) - CLI applications.
-- [swag](https://github.com/swaggo/swag) -  Swagger Documentation generate.
+- [swag](https://github.com/swaggo/swag) -  Swagger Documentation generate.