Skip to content

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

Description

@megemini

文档链接&描述 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    PFCCPaddle Framework Contributor Club,https://github.com/PaddlePaddle/community/tree/master/pfcc

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions