“Open source is this magical thing right? You release code, and the code gnomes come and make it better for you.
Not quite. There are lots of ways that open source is amazing, but it doesn’t exist outside the laws of physics. You have to put work in, to get work out.
You only get contributions after you have put in a lot of work. You only get contributions after you have users. You only get contributions after you have documentation.”
From @ericholscher guide to writing docs
- Hierarchical structure
- Missing content
- How to add pages
- Updating Docstrings
- Jina style guide
- Technical aspects of the the doc site
Jina documentation adheres to the following hierarchical structure. Each Jina product has its own section, containing three subsections below.
| Overview | A high level conceptual overview of the product. Introducing terms and broad architectural concepts. Content here should apply to all Jina users. For example, all users should understand what a Pod is, but only some users need to understand deployment on a GPU. |
| Developer Guides | Are technical how-to guides/tutorials which describe product features or implementations. Assumes basic knowledge of the product and related terms. |
| API References | Are detailed descriptions of the product API. Possibility auto-generated from docstrings or open API references. Describes how the methods work and which parameters can be used. |
If you find a gap in our documentation, please submit a GitHub issue here.
For getting started pages and developer guides:
-
A page can be written in Markdown or reStructuredText format.
-
Use a template from the page_templates folder.
-
Using Git, clone the repo:
git clone https://github.com/jina-ai/docs. -
Create a git new branch:
git checkout -b fix_pods. -
Your commit messages should following the standard Jina format seen here.
-
Add your file to the chapters folder.
-
Add your file to a table of contents.
-
Push your branch and create a pull request.
-
Add at least two people to your pull request review. One product manager and one developer.
-
You can preview how the docs website will look with your changes. Inside your pull request, navigate to checks and click 'preview with netlify'.
-
After the pull request is merged, the website will automatically update.
- A guide to RST can be found here
- A guide to MD formatting can be found here [Note that MD is more limited in functionality then RST]
See details here.
All documentation should follow this style guide.
#Clone the code.
git clone https://github.com/jina-ai/docs.git
#Install dependencies.
pip install -r requirements.txt
# Clean & build docs locally
make dirhtml
# Serve the docs website with Python 3
python -m http.server 8080 -d _build/dirhtml