apache / apache/dolphinscheduler

[DSIP-2][Doc] Refactor the document

Open
#6,535 31 comments 6 reactions 0 assignees View on GitHub
document DSIP good first issue good idea help wanted
Dominant language
Java
Stars
14.5k
Forks
5.1k
Avg merge
1d 21h
Merged PRs (30d)
28

Description

# Description

For now, we documentation is not easy enough to read and maintain. I think documentation is also an important for OSS, it would be

## General

* [x] Sperate `user_muanl/user_manal` to multiple file with different level. https://github.com/apache/dolphinscheduler-website/pull/453
* [ ] Add directory for our image file, start this task until all we markdown document is done.
* [ ] Find a way to use codebase repo directory icon files instead of copy-paste

## Content

### DRY

* [ ] remove duplicate content in the document, for example in installation we have duplicate download mysql dependent
* [ ] Many parameters of task have same definition, find a way to handle it. maybe we could see what `github/doc` do, https://github.com/github/docs

### Missing document

* [x] ~Chinese translation for [ambari integration][1]. @lukairui https://github.com/apache/dolphinscheduler-website/pull/494~ Our community going to drop support of Apache Ambari in the further, so we do not need this anymore.
* [ ] How to contribute to our document, including dev and older doc.
* [x] https://github.com/apache/dolphinscheduler/issues/6611
* [ ] 🔥 Missing Task: we missing some of our tasks in doc
* [ ] SQOOP
* [x] condition. https://github.com/apache/dolphinscheduler-website/pull/453
* [x] switch. https://github.com/apache/dolphinscheduler/issues/6561
* [ ] waterdrop
* [x] pigeon. https://github.com/apache/dolphinscheduler-website/pull/453
* [x] Task conditions screenshot https://github.com/apache/dolphinscheduler-website/pull/461
* [ ] 🔥 Missing alert plugin
* [ ] Alert plugin dingtalk apache/dolphinscheduler-website#650
* [ ] Alert plugin email
* [ ] Alert plugin feishu
* [ ] Alert plugin http
* [ ] Alert plugin script
* [ ] Alert plugin slack
* [ ] Alert plugin wechat
* [ ] 🔥 Missing datasource plugin
* [ ] Alert plugin clickhouse
* [ ] Alert plugin db2
* [ ] Alert plugin oracle
* [ ] Alert plugin sqlserver
* [ ] Inside DolphinScheduler
* [ ] How master node run
* [ ] How worker node run
* [ ] How master and worker community, and task lifecycle
* [ ] DolphinScheduler plugins development
* [ ] DolphinScheduler API
* [ ] API docs and example, provider curl command line would be better.

### To be classify

* [x] `user_doc/globalParam` https://github.com/apache/dolphinscheduler-website/pull/472
* [x] All the spi document for develpment. https://github.com/apache/dolphinscheduler/issues/6577
* [x] Unify `dev-run` and `dev-quick-start` https://github.com/apache/dolphinscheduler-website/pull/472

### To be update

* [ ] For now, task name much unify in the project
* [ ] `introduction.md`
* [x] 🔥 Installation https://github.com/apache/dolphinscheduler-website/pull/465
* [ ] 🔥 Task Usage: we should add basic usage, example, notict about tasks
* [x] #8016
* [x] #8017
* [x] #8018
* [x] #8019
* [x] #8020
* [x] #8021
* [x] #8022
* [x] #8023
* [x] #8024
* [x] #8025
* [x] #8026
* [x] #8027
* [x] #8028
* [x] #8029
* [x] #8030
* [x] #8031
* [ ] Picture in English doc have Chinese content
* [x] [design](https://dolphinscheduler.apache.org/en-us/docs/latest/user_doc/architecture/design.html),https://github.com/apache/dolphinscheduler/issues/7496
* [ ] architecture-design
* [ ] Task queue. https://github.com/apache/dolphinscheduler/discussions/7835
* [ ] Architecture diagram. https://github.com/apache/dolphinscheduler/discussions/7306
* [x] #7870

## Syntax

* [ ] Use markdown table syntax instead of html table syntax ``
* [ ] Find a better way to show our picture, for now it use html syntax in markdown file. I find our it can be show use [markdown image syntax][2], such as [this line][3]

## CI

* [ ] Add markdown link for our document
* [ ] Add chinese/english spelling ci for our doc
* [ ] Add document preview generation for each PR, example https://github.com/sqlfluff/sqlfluff/issues/808#issuecomment-787493894 . I think it really important to reduce doc build error, such as this PR https://github.com/apache/dolphinscheduler-website/pull/454, we get error dev leading page url make all our document error.
* [ ] Add doc style check for our documentation, inspired by https://github.com/apache/dolphinscheduler-website/pull/463#discussion_r734245581. maybe we could use https://github.com/tidb-incubator/zh.md

[1]: https://dolphinscheduler.apache.org/en-us/docs/latest/user_doc/integration/ambari.html
[2]: https://www.markdownguide.org/basic-syntax/#images
[3]: https://github.com/apache/dolphinscheduler-website/blob/master/docs/en-us/dev/user_doc/guide/parameter/context.md?plain=1#L9

Contributor guide

Open the contributing guide

Research direction

This is a broad documentation roadmap rather than a single change. Start by selecting one unchecked item and inspect the relevant documentation entry points, such as docs/en-us/dev/user_doc/guide/parameter/context.md or introduction.md; CI-related work should begin from the documentation build and validation setup. Done means completing one scoped item, verifying the affected documentation, and updating the checklist or linked issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
ci-cd, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.