docs: add troubleshooting section

docs/datatype/image/index.md

@@ -1,10 +1,20 @@
 # {octicon}`image` Image
 
+````{tip}
+
+To enable the full feature of Document API on image, you need to install `Pillow` and `matplotlib`.
+
+```shell
+pip install matplotlib pillow
+```
+````
+
 Images and pictures are probably the most intuitive data for a lot of people. Comparing to textual data, image data is more universal and easier to comprehend. Neural search on image can be fun: from good-old content-based image retrieval to text2image or image2text cross-modality retrieval. With Jina, one can build all kinds of fancy applications on image data. In this chapter, we will introduce some common tasks that can be built with Jina.
 
 Before we get started, let's recap what we know about image data.
 
 
+
 ## Image is `ndarray`
 
 Image data is often just `ndarray`. Strictly speaking, not any `ndarray` but an `ndarray` with `ndim=2` or `ndim=3` and `dtype=uint8`. Each element in that `ndarray` represents the pixel value between 0 and 255 on certain **channel** at certain **position**. For example, a colored JPG image of 256x300 can be represented as an `ndarray` [256, 300, 3]. Why 3 in the last dimension? Because it represents R, G, B channels of each pixel. Some image has different number of channels. For example, a PNG with transparent background has 4 channels, where the extra channel represents opacity. A gray-scale image has only one channel, which represents the luminance.

docs/datatype/video/index.md

@@ -1,12 +1,23 @@
 # {octicon}`device-camera-video` Video
 
+
+````{tip}
+
+To enable the full feature of Document API on video, you need to install `av`.
+
+```shell
+pip install av
+```
+````
+
 Video data is a common asset consumed on daily basis: live stream on Youtube/TikTok, CCTV camera or fun meme gifs. 
 
 Even though most applications of computer vision today center on images, thanks to those viral TikTokers, video data analysis has gained more attention recently, e.g. monitoring real-time video and analyzing archived video.
 
 Comparing to static image, video allows for deeper situational understanding, because sequences of images provide new information about action. For example, we can track an obstacle through a sequence of images and understand its behavior to predict the next move. We can track a human pose, and understand the action taken with action classification.
 
-Neural search on video often includes tasks such as in-video content search, video2video recommendation, video question-answering. Before you start to solve those tasks, let's take a quick tour on the video data format, and how Jina Document API can help you get started. 
+Neural search on video often includes tasks such as in-video content search, video2video recommendation, video question-answering. Before you start to solve those tasks, let's take a quick tour on the video data format, and how Jina Document API can help you get started.
+
 
 ## Video as sequence of images
 

docs/get-started/install/index.md

@@ -5,4 +5,5 @@
 :hidden:
 
 ../../advanced/experimental/windows
+troubleshooting
 ```

docs/get-started/install/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+This article helps you to solve the installation problems of Jina.
+
+## On Linux/Mac, building wheels takes long time
+
+The normal installation of Jina takes 10 seconds. If yours takes longer than this, then it is likely you unnecessarily built wheels from scratch. 
+
+Every upstream dependencies of Jina have pre-built wheels exhaustively on x86 & arm64 and on MacOS & Linux and on Python 3.7, 3.8, 3.9, including `numpy`, `protobuf`, `pyzmq`, `grpcio` etc. This means, when you install Jina, your `pip` should directly leverage the pre-built wheels instead of building them from scratch locally. For example, you should expect the install log to contain `-cp38-cp38-macosx_10_15_x86_64.whl` when installing Jina on MacOS with Python 3.8.
+
+Hence, if you found you are building wheels during installation (see an example below), then it is a sign that you are installing Jina **wrongly**. 
+
+```text
+Collecting numpy==2.0.*
+  Downloading numpy-2.0.18.tar.gz (801 kB)
+     |████████████████████████████████| 801 kB 1.1 MB/s
+Building wheels for collected packages: numpy
+  Building wheel for numpy (setup.py) ... done
+  Created wheel for numpy ... numpy-2.0.18-cp38-cp38-macosx_10_15_x86_64.whl
+```
+
+### Solution: update your `pip`
+
+It could be simply that your local `pip` is too old. Updating it should solve the problem.
+
+```python
+pip install -U pip
+```
+
+### If not, then...
+
+Then you are likely installing Jina on a less-supported system/architecture. For example, on native Mac M1, or on Alpine Linux, or on Raspberry Pi 2/3 (armv6/7).
+
+## On Mac M1
+
+Some upstream dependencies do not have pre-built wheels on M1 chip, hence you are likely to encounter some issues during the install. In this case, you need to config the dev environment using Rosetta2, including your terminal, `brew` and `python`, they must be running under Rosetta2 instead of natively on M1.
+
+````{tip}
+You can run the following shell scrit in the terminal to check if you are running under Rosetta2 or natively on M1.
+
+```shell
+sysctl -n -i sysctl.proc_translated
+```
+
+Depending on the results:
+- `0`: for Apple silicon native process
+- `1`: for Rosetta2 translated process
+- `""`: in case the OID was not found, you are using an older mac running Catalina or something. You don't have the M1 problem in the first place.
+````
+
+## On Windows with `conda`
+
+Unfortunately, `conda install` is not supported on Windows. You can either do `pip install jina` natively on Windows, or use `pip/conda install` under WSL2.