V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
lingeo
V2EX  ›  程序员

一个项目的 README.md 应该如何编写

  •  
  •   lingeo · 341 天前 · 2706 次点击
    这是一个创建于 341 天前的主题,其中的信息可能已经有所发展或是发生改变。

    有没有如何编写 README.md 的规范?每次写文档都难受的要死,删了改改了删,最后写出来自己都读不下去😟。

    16 条回复    2023-04-24 08:15:49 +08:00
    yolee599
        1
    yolee599  
       341 天前
    不想自己写 github 上找一个自己喜欢的模仿不就行了
    lsk569937453
        2
    lsk569937453  
       341 天前
    很简单啊,先找你的开源竞品看看他们是怎么写的。
    weeei
        3
    weeei  
       341 天前
    这个困扰付费可破。
    icyalala
        4
    icyalala  
       341 天前   ❤️ 3
    https://github.com/othneildrew/Best-README-Template
    https://github.com/matiassingers/awesome-readme
    多看看,选一些自己喜欢的模仿一下,没内容就就让 GPT 帮一下
    mringg
        5
    mringg  
       341 天前 via iPhone
    个人感觉,也不用太复杂,但是关键的信息得有。
    默认编译环境:操作系统版本,编译器的版本
    运行依赖:操作系统,runtime ,其他中间件版本等
    产品相关:产品原型地址,设计图地址
    如果有啥重要的提醒,再补充下就好了
    darksword21
        6
    darksword21  
       341 天前   ❤️ 2
    就写 WIP
    lingeo
        7
    lingeo  
    OP
       341 天前
    @icyalala 这个好,感谢。
    tyzandhr
        8
    tyzandhr  
       341 天前 via Android   ❤️ 1
    就像教材一样写啊,如何 get started ,如何使用 api 或者如何配置,背后的原理,如何贡献代码
    ufo5260987423
        9
    ufo5260987423  
       341 天前   ❤️ 1
    根据项目内容和状态,不同阶段要有不同的写法。最关键的是你要知道自己项目的用户在想啥。

    拿我自己的项目举例: https://github.com/ufo5260987423/scheme-langserver

    1 、要介绍这个项目是干啥的,两三句解决掉;
    2 、介绍这个项目的背景和发行方式,一段话两三句。
    3 、使用效果,最好带上图,这块可以多弄一点,要一下子抓住人家的眼球;
    4 、如果是开发过程中的项目,交代一下开发状态;如果已经发布了若干个版本,要简单介绍一下各个版本干了啥;
    5 、如何使用、部署、编译项目,要让人家顺着你这个介绍一步步就能把项目用起来;
    6 、描述一下愿景:我将来要发什么功能;
    7 、如何测试、debug
    以及其他。

    其实如果你写过论文的话,这些都是很正常的东西。
    lete
        10
    lete  
       341 天前
    不用写太多,就开头说明你这个项目的作用,写个简介,下面写使用方法和一些注意事项就可以了

    可看看这个: https://github.com/CreateWheel/tinydateformat2
    artnowben
        11
    artnowben  
       341 天前
    1. 支持中英文,虽然是中文用户居多,但是英文也要支持
    2. 说明项目的用途,有什么优势,有测试数据支撑
    3. quick start 部分:如何编译,运行一个简单的例子
    4. Documentation:列出使用文档,设计文档的链接等
    5. Related Articles(相关文章):新闻、博客文章
    6. License
    7. 作者 (可选)
    8. 如何贡献 (可选)

    开源网络性能测试仪 dperf 的 readme 供参考:
    https://github.com/pengjianzhang/dperf
    nashaofu
        12
    nashaofu  
       341 天前 via iPhone
    github 上有人使用 chatgpt 生成 readme 的,地址不记得了。使用下来挺好的,而且可以帮你做 readme 翻译,例如中文 readme 生成英文的,翻译水平比我高太多了
    litchinn
        13
    litchinn  
       341 天前
    介绍下干嘛的
    介绍下特点
    介绍下怎么用
    如果项目大,将项目的详细文档链接贴出来
    krapnik
        14
    krapnik  
       341 天前
    DIO
        15
    DIO  
       341 天前
    我觉得最基本就是介绍(突出亮点)和使用方法吧。其他的按需添加
    majula
        16
    majula  
       340 天前
    readme 不是文档

    用客观简洁的话描述一下你的项目是干什么用的即可。如果真的有人想用你的项目,会自行到项目根目录下找 "doc" "man" 之类的目录来看文档,看 tag 找 release

    当然如果文档没有和源码放一个仓库,视情况也可以带上文档或者项目官网的链接。同理也可以带上 prebuilt binaries 的下载地址
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2669 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 34ms · UTC 15:27 · PVG 23:27 · LAX 08:27 · JFK 11:27
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.