docs: multiple improvements (#3215)

website/docs/contributing/_category_.yml → website/community/committers/_category_.yml

@@ -16,9 +16,9 @@
 # under the License.
 
 position: 5
-label: 'Contributing'
+label: 'Committers'
 collapsible: true
 collapsed: true
 link:
   type: generated-index
-  title: Contributing
+  title: Committers

website/docs/contributing/committer.md → website/community/committers/committer.md

@@ -1,5 +1,5 @@
 ---
-title: Committer Onboarding
+title: Committer onboarding
 sidebar_position: 3
 ---
 

website/docs/contributing/podling-report.md → website/community/committers/podling-report.md

@@ -1,5 +1,5 @@
 ---
-title: Podling Status Reports
+title: Podling status reports
 sidebar_position: 4
 ---
 

website/docs/contributing/reference/generate_release_note.md → website/community/committers/reference/generate_release_note.md

@@ -1,5 +1,5 @@
 ---
-title: Generate Release Note
+title: Generate release note
 ---
 
 This document describes how to generate release notes using GitHub:

website/docs/contributing/reference/setup_gpg.md → website/community/committers/reference/setup_gpg.md

@@ -1,8 +1,12 @@
 ---
-title: Setup GPG Key
+title: Setup GPG key
 ---
 
-> This section is a brief from the [Cryptography with OpenPGP](https://infra.apache.org/openpgp.html) guideline.
+:::note
+
+This section is a brief from the [Cryptography with OpenPGP](https://infra.apache.org/openpgp.html) guideline.
+
+:::
 
 ## Install GPG
 

website/docs/contributing/release.md → website/community/committers/release.md

@@ -1,5 +1,5 @@
 ---
-title: Release
+title: Create a OpenDAL Release
 sidebar_position: 1
 ---
 

website/docs/contributing/verify.md → website/community/committers/verify.md

@@ -1,5 +1,5 @@
 ---
-title: Verify
+title: Verify a release candidate
 sidebar_position: 2
 ---
 

website/community/index.md

@@ -0,0 +1,65 @@
+---
+id: community
+title: Community
+sidebar_position: 1
+---
+
+Every volunteer project obtains its strength from the people involved in it. We invite you to participate as much or as little as you choose.
+
+You can:
+
+* Use our project and provide a feedback.
+* Provide us with the use-cases.
+* Report bugs and submit patches.
+* Contribute code, documentation.
+
+## Mailing list
+
+| Name                       | Desc                            | Subscribe                                                | Unsubscribe                                                  | Post                                   | Archive                                                                  |
+|----------------------------|---------------------------------|----------------------------------------------------------|--------------------------------------------------------------|----------------------------------------|--------------------------------------------------------------------------|
+| [email protected]     | Development related discussions | [Subscribe](mailto:[email protected])     | [Unsubscribe](mailto:[email protected])     | [Post](mailto:[email protected])  | [Archive](https://lists.apache.org/[email protected])     |
+| [email protected] | All commits to our repositories | [Subscribe](mailto:[email protected]) | [Unsubscribe](mailto:[email protected]) | Read only list                         | [Archive](https://lists.apache.org/[email protected]) |
+
+
+Please make sure you are subscribed to the mailing list you are posting to!
+
+If you are not subscribed to the mailing list, your message will either be rejected or you won't receive the response.
+
+### How to subscribe to a mailing list
+
+Before you can post a message to a mailing list, you need to subscribe to the list first.
+
+1. Send an email without any contents or subject to [email protected]. (replace listname with dev or user)
+2. Wait till you receive an email with the subject "confirm subscribe to [email protected]". Reply to that email, without editing the subject or including any contents.
+3. Wait till you receive an email with the subject "WELCOME to [email protected]".
+
+If you email us with a code snippet, make sure that:
+
+* you do not link to files in external services as such files can change, get deleted or the link might break and thus make an archived email thread useless
+* you paste text instead of screenshots of text
+* you keep formatting when pasting code in order to keep the code readable
+* there are enough import statements to avoid ambiguities
+
+## Issue tracker
+
+We use GitHub Issues to track all code related issues: https://github.com/apache/incubator-opendal/issues
+
+You must have a [GitHub account](https://github.com/signup) in order to log cases and issues.
+
+### Bug reports
+
+Found bug? Enter an issue in the issue tracker.
+
+Before submitting an issue, please:
+
+* Verify that the bug does in fact exist.
+* Search the issue tracker to verify there is no existing issue reporting the bug you've found.
+* Consider tracking down the bug yourself in the source code of OpenDAL and submitting a patch along with your bug report. This is a great time saver for the OpenDAL developers and helps ensure the bug will be fixed quickly.
+
+### Enhancement
+
+Enhancements or new feature proposals are also welcome. The more concrete and rationale the proposal is, the greater the chance it will be incorporated into future releases.
+
+## Source code
+
+* OpenDAL core repository: https://github.com/apache/incubator-opendal

website/community/sidebars.js

@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  docs: [{ type: 'autogenerated', dirName: '.' }],
+};
+
+module.exports = sidebars;

website/docs/overview.md

@@ -9,8 +9,64 @@ OpenDAL represents **Open** **D**ata **A**ccess **L**ayer. Our vision is to **ac
 
 ![](https://user-images.githubusercontent.com/5351546/222356748-14276998-501b-4d2a-9b09-b8cff3018204.png)
 
-See the page for our vision in details: [Vision](vision.md).
-
 ## Getting started
 
-See the page for quick start with multiple languages: [Getting started](getting-started.md).
+See the page for quick start with multiple languages: [Quickstart](quickstart.md).
+
+## Why OpenDAL?
+
+The vision of OpenDAL is access data freely, where "free" refers to four essential aspects:
+
+### 1. Free from services
+
+OpenDAL must enable users to access various storage services ranging from `s3` to `dropbox` via its own native API. It should provide a unified API for accessing all these services.
+
+For example, we DO
+
+- Add support for [Google Drive](https://www.google.com/drive/): It allows users to access and manage their data on the [Google Drive](https://www.google.com/drive/).
+- Add support for [Object Storage Service (OSS)](https://www.alibabacloud.com/product/object-storage-service) via native API: Users can utilize Aliyun's RAM support.
+- Add support for [supabase storage](https://supabase.com/docs/guides/storage): Users can visit `supabase storage` now!
+
+while we DO NOT
+
+- Add support for [Google Cloud Storage(GCS)](https://cloud.google.com/storage) via [XML API](https://cloud.google.com/storage/docs/xml-api/overview): [GCS](https://cloud.google.com/storage) has native [JSON API](https://cloud.google.com/storage/docs/json_api) which more powerful
+- Add support for structural data in `MySQL/PostgreSQL`: We can treat a database as a simple key-value store, but we can't support unified access of structural data.
+
+### 2. Free from implementations
+
+OpenDAL needs to separate the various implementation details of services and enables users to write identical logic for different services.
+
+For example, we DO
+
+- Add a new capability to indicate whether `presign` is supported: Users can now write logic based on the `can_presign` option.
+- Add a `default_storage_class` configuration for the S3 service: Configuration is specific to the S3 service.
+- Add an option for `content_type` in the `write` operation: It aligns with HTTP standards.
+
+while we DO NOT
+
+- Add a new option in read for `storage_class`: As different services could have varying values for this parameter.
+
+### 3. Free to integrate
+
+OpenDAL needs to be integrated with different systems.
+
+For example, we DO
+
+- Add Python binding: Python programmers can use OpenDAL.
+- Add object_store integration: `object_store` users can adopt OpenDAL.
+
+### 4. Free to zero cost
+
+OpenDAL needs to implement features in zero cost way which means:
+
+- Users need not to pay cost for unused features.
+- Users cannot write better implementation for used features.
+
+For example, we DO
+
+- Add `layer` support: Users can add logging/metrics/tracing in zero cost way.
+- Implement `seek` for Reader: Users cannot write better `seek` support, they all need to pay the same cost.
+
+we DO NOT
+
+- Add `Arc` for metadata: Users may only need to use metadata once and never clone it. For those who do want this feature, they can add `Arc` themselves.

website/docs/getting-started.md → website/docs/quickstart.md

@@ -1,5 +1,5 @@
 ---
-title: Getting started
+title: Quickstart
 sidebar_position: 3
 ---
 
@@ -131,8 +131,11 @@ For details in specifying classified library, read the [dedicated explanation](h
 Try it out:
 
 ```java
+// Configure service
 final Map<String, String> conf = new HashMap<>();
-final Operator op = Operator.of("memory", conf);
+conf.put("root", "/tmp");
+// Construct operator
+final Operator op = Operator.of("fs", conf);
 // Write data
 op.write("hello.txt", "Hello, World!").join();
 // Read data
@@ -143,8 +146,20 @@ op.delete("hello.txt").join();
 
 ## Python binding
 
+OpenDAL's Python binding is released to PyPI repository as [`opendal`](https://pypi.org/project/opendal/).
+
+### Install
+
+Run the following command to install `opendal`:
+
+```shell
+pip install opendal
+```
+
 ### Demo
 
+Try it out:
+
 ```python
 import opendal
 import asyncio
@@ -159,8 +174,20 @@ asyncio.run(main())
 
 ## Node.js binding
 
+OpenDAL's Python binding is released to npm registry as [`opendal`](https://www.npmjs.com/package/opendal).
+
+### Install
+
+Run the following command to install `opendal`:
+
+```shell
+npm install opendal
+```
+
 ### Demo
 
+Try it out:
+
 ```javascript
 import { Operator } from "opendal";
 

website/docs/services/http.mdx

@@ -1,5 +1,5 @@
 ---
-title: Http
+title: HTTP
 ---
 
 HTTP Read-only service support like [Nginx](https://www.nginx.com/) and [Caddy](https://caddyserver.com/).