PaddlePaddle / PaddlePaddle/docs

【Docs 文档吐槽大会】中文文档的书写

Open
#6,462 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

PFCC
Dominant language
Python
Stars
284
Forks
906
PR merge metrics
No merged PRs in 30d

Description

文档链接&描述 Document Links & Description

中文文档书写时,遇到几个问题:

  1. 一个文档可能涉及多个地方的修改,如 xxx_cn.rst, Overview_cn.rst(又可能存在多级), Tensor_cn.rst, pytorch_api_mapping_cn.rst 等,一不小心就遗漏了。
    建议:在《文档贡献指南》中增加引导,在哪里增加的 api,需要对应 增加/修改 哪些中文文档。或者,只需要开发者添加中文文档,文档结构由工具根据英文文档生成,从而保持一致性。

  2. Tensor_cn.rst 书写不规范,仍存在第一个 Tensor 参数,如:

multi_dot(x, name=None)
:::::::::

建议:增加参数检查,或者由工具根据中英文文档自动生成,并删除第一个参数。

  1. pytorch_api_mapping_cn.rst 太乱了,有的还要写编号,有的 api 要写多个地方。

建议:重构,并增加不同类型书写指导,如,“仅参数名不同”:表示xxx,“参数不同”:表示xxx

补充:pfcc 的 blog 中增加类似“周报”/“研发通报”的专栏,及时拉平飞桨内部研发与开源社区的信息差,作为官方文档之外的补充,及时通告,如,某关键 PR 需要合入,会影响xxx。

请提出你的建议/提个PR修复这个问题 Please give your suggestion/update a PR to fix it

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the 文档贡献指南 and the referenced xxx_cn.rst, Overview_cn.rst, Tensor_cn.rst, and pytorch_api_mapping_cn.rst files to map the current Chinese documentation workflow. The issue covers several possible tooling, structure, validation, and communication changes, so a concrete scope and acceptance criteria are needed before implementation can be considered done.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.