Skip to content

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

Open
@megemini

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

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