V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
star7th
V2EX  ›  分享创造

可能是国内颜值最高的开源文档工具?

  •  
  •   star7th · 2023-06-28 09:26:31 +08:00 · 18985 次点击
    这是一个创建于 533 天前的主题,其中的信息可能已经有所发展或是发生改变。

    地址

    开源地址: https://github.com/star7th/showdoc

    官网: https://www.showdoc.com.cn/

    开发小故事

    早前,showdoc 发布过 3.0 UI 重构版,但是尚未完全达到设计预期,属于略微仓促发布的版本。在那个时候,设计师委婉地说过,他习惯一步到位,做完善产品了再上线。意思是想我更完善 showdoc 再发布。

    我跟他就这个观点进行了交流,还蛮有意思的。这是两种风格迥异的产品思维。一种是把产品打磨得很好,一出场就惊艳用户。一种是小步快走,分阶段迭代。实际上,我也看过设计师的其他作品,确实给人的第一感觉就很惊艳,其产品给目标用户的第一印象非常好。

    对于 showdoc 项目而言,我要照顾到开发时间成本和宣发机会,我比较愿意追求留给用户一种 “这个产品一直在优化在进步”的印象,而不需花太长的时间“憋大招”来惊艳用户。

    于是在 3.0 版发布了一段时间后的今天,3.2 完全版也出来了。本轮更新,在设计师的“像素眼”注视下,修改了大量细节,优化了很多视觉 UI 和交互体验。

    3.2 版本更新了什么

    • 文档目录数支持拖曳排序和右键菜单操作,可以快速添加页面以及子文件等
    • 优化移动端访问项目的效果
    • 更换了更好看的产品图标
    • 优化小屏设备的访问效果
    • 将大多有跟 页面 有关的操作移动到文档目录树底部操作栏
    • 其它小细节

    相关截图

    给新用户看的 showdoc 介绍

    ShowDoc 是一个非常适合 IT 团队的在线 API 文档、技术文档工具,既有开箱即用的在线托管服务版,也有免费的开源版( github 1 万+ star )。通过 showdoc ,你可以方便地使用 markdown 语法来书写出美观的 API 文档、数据字典文档、技术文档、在线 excel 文档等等。如果不想编辑 markdown 文档,你还可以利用 showdoc 的自动化能力,从程序注释中自动生成 API 文档,或者从搭配的 RunApi 客户端(类似 postman 的 api 调试工具)中一边调试接口、一边自动生成文档。无需手动编写文档,释放生产力。通过分配项目成员和团队成员,你可以很方便地进行项目文档的权限管理和团队协作,也可以分享文档出去给朋友查看。ShowDoc 还支持多平台客户端,有 win 客户端、mac 客户端、ios 、android 等,更方便跨平台使用。目前超过 100000+的互联网团队正在使用 showdoc ,包括知名公司内部的一些团队,比如腾讯、华为、百度、京东、字节跳动等等。

    关于 Showdoc 的详细介绍,请看: https://www.showdoc.com.cn/help

    第 1 条附言  ·  2023-06-28 10:49:00 +08:00
    感觉这个标题似乎 招来了一些不友好的言论 。

    如果硬要从客观上看,本标题并没有脱离事实太多,因为国内开源文档工具很少,我在一个小众产品领域里说可能 [颜值] 最高,虽然不是非常离谱的乱说,但是也不算厚道谦虚,所以可能激起了某些人的反感情绪。

    所以我承认这个标题起得不算好了。下次不这样起标题了。

    后面的人就暂且不要从标题上讨论了,重点关注讨论下产品本身吧。
    第 2 条附言  ·  2023-06-28 12:03:35 +08:00
    V 站不能改标题,所以这个标题我暂时没法修正了。也不知道后来者能不能看到文后的附言,不用再标题上深究下去了。不然我每个人解释一下,也很累的( ╯□╰ )

    其实,showdoc 开源项目都维护 7 年了,我如果真的很浮躁地运营产品,只靠哗然宠,是坚持不了那么多年的。大部分时候都是默默踏实完善产品。此次是宣发的时候,失误地想标题党一下,想吸引下流量。正文还是比较中规中矩的宣发。
    各位就不要死抓我这次标题的失误,谢谢啦。
    234 条回复    2023-07-09 13:44:26 +08:00
    1  2  3  
    ggp1ot2
        1
    ggp1ot2  
       2023-06-28 09:34:27 +08:00   ❤️ 16
    之前用过,你要是说小清新还行, [颜值最高] 是怎么有自信的?
    vayci
        2
    vayci  
       2023-06-28 09:36:38 +08:00
    暂时不可能
    star7th
        3
    star7th  
    OP
       2023-06-28 09:37:03 +08:00
    @ggp1ot2

    你可以尝试发一下你认为颜值最高的国内开源文档工具来让我学习下?
    star7th
        4
    star7th  
    OP
       2023-06-28 09:37:54 +08:00
    @vayci

    尝试发一下你认为颜值最高的国内开源文档工具来让我学习下?
    LavaC
        5
    LavaC  
       2023-06-28 09:39:39 +08:00
    该想个办法忽悠后端用上
    ggp1ot2
        6
    ggp1ot2  
       2023-06-28 09:46:44 +08:00   ❤️ 38
    @star7th


    没法提供,只是单纯觉得 [国内最 xxx] 式的标题很讨厌

    要想说 [国内颜值最高的开源文档工具] ,有点过于太得意了,谁给你的勇气,还是想靠标题党吸引人用?

    可以看出比上个版本 ui 更现代化一点,可能是花了很多心思

    个人认为,作为开发者应该谦虚一点

    最后,这个 ui ,真的就一般,很多 typore 主题都能秒杀
    nekoneko
        7
    nekoneko  
       2023-06-28 09:47:47 +08:00   ❤️ 1
    一直在用, 挺好的, 支持一下.
    rzdCG
        8
    rzdCG  
       2023-06-28 09:49:10 +08:00
    没有 Linux 差评
    star7th
        9
    star7th  
    OP
       2023-06-28 09:51:07 +08:00
    @ggp1ot2

    typore 不开源,不在比较的范围内。

    我起这个标题的时候,其实是调查过了的。基本符合事实。当然,为了防止翻车,我加上了“可能” 两字。
    如果不符合事实,你大可找反例来反驳我,我承认我的孤落寡闻后,回去默默提高产品体验。
    但是如果是符合事实的,那为什么不能把 产品的优点(颜值)拿出来做一下宣传呢。所以我起了这个标题。
    iblessyou
        10
    iblessyou  
       2023-06-28 09:51:21 +08:00
    为啥不像 swagger 那样自己本地给启个服务呢
    star7th
        11
    star7th  
    OP
       2023-06-28 09:52:44 +08:00
    @nekoneko

    多谢支持
    mydingyan
        12
    mydingyan  
       2023-06-28 09:53:09 +08:00
    更新 3.0 以后,安卓端 app 项目主页一直白屏的,是不是忘记兼容啦
    版本号:1.1.1
    star7th
        13
    star7th  
    OP
       2023-06-28 09:55:19 +08:00
    @rzdCG

    showdoc 是网站为主的,基本全平台的浏览器都可访问。
    你说的没有 linux ,应该指的是客户端吧。其实 showdoc 客户端也只是一个 web 打包,我统计了下使用率也没有很高,大部分用户还是直接通过 web 访问的。
    lmoon
        14
    lmoon  
       2023-06-28 09:57:08 +08:00
    如果说,我就是如果说啊,算上国外呢
    star7th
        15
    star7th  
    OP
       2023-06-28 09:57:58 +08:00
    @iblessyou

    我没有看到 这种本地启动服务的方式 比 showdoc 现在的方式 有明显的好处。
    seth19960929
        16
    seth19960929  
       2023-06-28 09:58:56 +08:00
    用 showdoc 写 API 文档, 到底图 什么呢
    star7th
        17
    star7th  
    OP
       2023-06-28 09:59:34 +08:00   ❤️ 1
    @lmoon

    所以我保守一点,加上了明显的国内范围限制,免得有人喷我标题党。
    目前来看,这个标题还是基本符合事实的。如果连 符合事实 的标题都看不惯,只能说某些人纯属只是看不得别人好。
    zq11211277
        18
    zq11211277  
       2023-06-28 10:00:04 +08:00
    很好用
    但颜值可能不是最高的,这个不影响
    whyzp2019
        19
    whyzp2019  
       2023-06-28 10:00:19 +08:00   ❤️ 3
    审美是一个非常主观的东西,你拿着个跟别人顶,属实是不太明智,人家觉得这个不好看,也并不一定就会有觉得更好看的,同时,同意前楼的说法,像 swagger 那样起个服务,我一定程度上都不用开 postman
    star7th
        20
    star7th  
    OP
       2023-06-28 10:02:17 +08:00
    @seth19960929

    因为要写 api 文档给团队的其他成员看。比如后端写给前端看。
    如果不想手写 api 文档,可以用 runapi 来自动生成 https://www.showdoc.com.cn/runapi
    wu00
        21
    wu00  
       2023-06-28 10:02:50 +08:00
    优势是私有化部署很方便;
    另外 html 代码必须压缩,否则标签之间的换行会导致解析成<br/>
    比如:
    <table>
    <td>
    xxx
    </td>
    </table>
    这个解析出来一堆 br
    xiaoz
        22
    xiaoz  
       2023-06-28 10:02:56 +08:00
    用了 showdoc 一段时间了,首先表示感谢。

    看了下新版,感觉变化不大啊。另外语雀的文档我觉得还挺好看的,但不支持私有部署。
    yhxx
        23
    yhxx  
       2023-06-28 10:06:10 +08:00
    确实不是很好看。。。

    楼主想要反例的话,我来举一个栗子吧
    yhxx
        24
    yhxx  
       2023-06-28 10:06:29 +08:00
    https://github.com/antvis/gatsby-theme-antv
    不小心按错发出去了
    antv 应该算是国内的吧
    star7th
        25
    star7th  
    OP
       2023-06-28 10:07:02 +08:00
    @whyzp2019

    我同意你的说法,审美是很主观的。
    不过我没有跟别人顶,是别人跟我顶。目前我说的话,发布的文字,基本符合事实,没有脱离事实的夸大。
    swulling
        26
    swulling  
       2023-06-28 10:07:46 +08:00   ❤️ 5
    看了下示例文档,感觉也不是很讲究。对前端设计不熟,就以你们的官方文档页面( https://www.showdoc.com.cn/help/1385767280275683 ) 为例,说说文档的内容存在的问题吧:

    1. 「 ShowDoc 部署手册请参考」:中英文混排时没有在英文和中文间留白(不管你是 CSS 控制还是手动增加空格的方式),造成阅读上感觉很拥挤。
    2. Markdown 格式的文档,存在大量的直接超链接,比如:「如果你没有自己的服务器,但又想使用 ShowDoc 作为文档分享工具,你可以使用在线的 ShowDoc http://www.showdoc.com.cn 」。
    3. 「 showdoc 支持网页版、手机 app 版和电脑客户端版。」:关键英文名词时而大写 ShowDoc ,时而小写 showdoc 。
    4. Markdown 中的代码,在复制的时候,每一行开头都增加了空格。


    至于外在颜值我也觉得也比较一般。
    star7th
        27
    star7th  
    OP
       2023-06-28 10:08:06 +08:00
    @wu00

    markdown 编辑器会把换行符翻译为换行,所以输入 html 标签的时候,标签与标签之间不要包含换行,会被转义为 br 换行或者 p 段落。
    Jynxio
        28
    Jynxio  
       2023-06-28 10:09:08 +08:00   ❤️ 2
    1.我赞同 @ggp1ot2 和 @vayci 的观点,我也认为 showdoc 的审美很平庸,它不可能是「国内颜值最高的 XXX 」
    star7th
        29
    star7th  
    OP
       2023-06-28 10:10:11 +08:00
    @yhxx

    好像跟 showdoc 不是同一类的产品。不过确实看起来不错。我可以参考下
    seth19960929
        30
    seth19960929  
       2023-06-28 10:10:40 +08:00
    @star7th 我并没有说不写 API 文档, 我指的是用 showdoc. 为什么不用 yapi, apifox 之类的工具呢. showdoc 又不能发送请求. mock 数据, 接口测试. 光看?
    star7th
        31
    star7th  
    OP
       2023-06-28 10:11:06 +08:00
    @swulling

    非常感谢你这样有理有据的反馈。我根据你说的内容优化下。
    star7th
        32
    star7th  
    OP
       2023-06-28 10:12:30 +08:00
    @seth19960929

    runapi 能发送请求能 mock 数据和接口测试,并且自动生成文档到 showdoc https://www.showdoc.com.cn/runapi

    showdoc 的定位是 文档 。你说的这些需求,用 runapi 都能满足。
    shuxhan
        33
    shuxhan  
       2023-06-28 10:12:33 +08:00
    个人感觉 https://vitepress.dev/guide/what-is-vitepress 颜值更耐打,细节方面处理的比较好
    op 的这个虽然小清新,但是总感觉怪怪的
    比如主体部分的阴影就很生硬,并且在跳转的时候没发现侧栏会闪动吗,这个属实不应该,可以优化一下
    包括字体大小和颜色方面可以好好琢磨一下,还有很大的优化空间
    whyzp2019
        34
    whyzp2019  
       2023-06-28 10:13:44 +08:00
    @star7th 目前你说的话,只能符合你认知内的实事,并不代表别人的,你觉得没有夸大,别人未必这么觉得,所以别人说你的可能最好看是吹牛,你就认为别人在跟你顶,然后你就顶回去了呗。其实你换个方法提问,评论区会和谐很多,当然,是否和谐也无所谓,你觉得好看就好看就是了,心情不受影响就 ok 了
    star7th
        35
    star7th  
    OP
       2023-06-28 10:14:19 +08:00
    @Jynxio

    你可以尝试发一下你认为的 「国内颜值最高的 XXX 」 。

    如果你能像 26 楼那样有理有据列出来,我会虚心接受你意见。
    但是如果只是发泄情绪,那我觉得你这么说,没有必要。
    bjzhush
        36
    bjzhush  
       2023-06-28 10:14:20 +08:00   ❤️ 13
    说真的丑爆了!!!!
    功能另说!!!
    star7th
        37
    star7th  
    OP
       2023-06-28 10:16:03 +08:00
    @bjzhush

    如果你能像 26 楼那样有理有据列出来,我会虚心接受你意见。
    但是如果只是发泄情绪,那我觉得你这么说,没有必要。
    star7th
        38
    star7th  
    OP
       2023-06-28 10:17:45 +08:00
    @shuxhan

    你发的这个,应该是高仿 gitbook 的设计。我后面学习参考下。
    ZGame
        39
    ZGame  
       2023-06-28 10:17:53 +08:00
    @star7th 可以关注一下 AFFINE 这个项目。目前在我心里这个是文档类开源 No.1
    https://github.com/toeverything/AFFiNE
    star7th
        40
    star7th  
    OP
       2023-06-28 10:20:43 +08:00
    @xiaoz

    新版的变化主要在于 ,左侧目录树支持拖动支持右击操作等等,比之前的操作方式省事不少。
    还有移动端的样式也优化了很多,方便手机用户查看。比如说可以放一些 app 产品帮助文档,分享到手机给用户看。
    molvqingtai
        41
    molvqingtai  
       2023-06-28 10:20:45 +08:00
    很...简约
    star7th
        42
    star7th  
    OP
       2023-06-28 10:21:54 +08:00
    @ZGame

    好的,我留意参考下这个项目
    ggp1ot2
        43
    ggp1ot2  
       2023-06-28 10:23:30 +08:00
    @star7th

    [但是如果是符合事实的,那为什么不能把 产品的优点(颜值)拿出来做一下宣传呢。所以我起了这个标题。]
    [如果连 符合事实 的标题都看不惯,只能说某些人纯属只是看不得别人好]

    本意不是要争吵,我只是想知道,为什么你觉得 [showdoc 是国内颜值最高的开源文档工具] 是事实?从何得出。

    如上所说,颜值这玩意,是很主观的东西,你没法说某个东西好看,就是既定的事实,哪怕你做的再好。

    例如,只看你贴出来的几个截图
    - 表格标题栏,就是第一行,黑色填充,要多丑有多丑
    - 代码框左上角仿 mac 的设计,我就觉得很丑
    - 再比如我可以说我行距、间隙、padding 、margin 等多个细节,都不是我喜欢的

    另外,关于 showdoc ,我之前就发帖问过一些好用的文档工具,也了解并部署过一次,但是上个版本的 ui 只有一个字「丑」,仿佛是上个世纪的产物,这次升级,确实能看到整体风格更符合审美。

    最后,我还是要强调,一切 [最 xxxx] 的形容,都是主观的,不可能是事实,哪怕你加了再多的限定
    jixule
        44
    jixule  
       2023-06-28 10:26:03 +08:00
    官网示例,点右上的全屏,再点缩小不回来了?
    bjzhush
        45
    bjzhush  
       2023-06-28 10:26:53 +08:00   ❤️ 8
    @star7th #37 你接受不接受无所谓,但是说实话,确实丑,大块的黑色配上粗糙的截图,看起来就像个设计师午饭之后随便捣鼓了几下子的作品,也像个半吊子前端练手的作品。
    至于你说的什么有理有据,我是写后端的,我没法从 UI 的角度提出专业性的意见,但是确实是非常丑,看起来像是十年前的作品,完全没有现代化
    然后个人觉得你过于自恋,之前就看过你的 showDoc ,当时觉得功能尚可,但是界面过于粗糙,当时觉得可能是后端捣鼓的,丑就丑了吧,凑合能用,毕竟像我这样的人,一直把实用和功能放在第一位,也就没想什么,但是你是怎么好意思说什么国内最好看的开源文档工具的?就欺负好看的不开源,开源的不好看呗,欺负老外不能跟你同台对比呗?
    大家是礼貌,是包容,但是不是瞎啊。。。
    我知道 showdoc 或许很多用户,但这完全不影响我对你的作品和你做出这样的判断和评价。
    最后送你一句话,满招损谦受益
    不用回怼我了,本来我是不想和你争论的,你非得让我有理有据,看不惯的话你就当个 SB 一笑而过呗~~
    已经 block 你,欢迎 block 我
    star7th
        46
    star7th  
    OP
       2023-06-28 10:27:34 +08:00
    @ggp1ot2

    你如果觉得我不应该得出 [showdoc 可能是国内颜值最高的开源文档工具] 的事实 。要不我们用反证法来有理有据反驳一下?比如你觉得哪些同类产品更好?
    star7th
        47
    star7th  
    OP
       2023-06-28 10:29:34 +08:00
    @jixule

    我这边试了下,是可以点回来的。你尝试刷新页面再试。
    star7th
        48
    star7th  
    OP
       2023-06-28 10:31:54 +08:00
    @bjzhush

    我没觉得你是礼貌是包容。你可以回头看我所有发布过的话,我全部都是在有理有据地说话。包括别人提出了好的意见,发了其他好的产品,我也说我愿意虚心接受和学习。

    但是就你的发言,一会儿 说 丑爆 , 一会儿说 SB ,我不觉得你是多友好的讨论。你要 block 就 block ,不用告诉我。
    lilei2023
        49
    lilei2023  
       2023-06-28 10:31:56 +08:00
    比起之前的确实好多了,但是距离能用到“颜值”这个词,还差点
    Retas
        50
    Retas  
       2023-06-28 10:32:28 +08:00
    1.官网的黑白配色有点难绷,很难说颜值高
    2.最后一张图,Markdown 的 H1 - H6 图标个人觉得观感很差
    UI 设计只能说是正常水平
    zhaol
        51
    zhaol  
       2023-06-28 10:32:34 +08:00   ❤️ 3
    自己评价自己颜值最高,不允许别人评价不好看吗?本来就是很主观的东西。还有你这个调查在哪调查的,有没有说服力。我也认同 1 楼,小清新还行,颜值高谈不上
    star7th
        52
    star7th  
    OP
       2023-06-28 10:34:55 +08:00
    @Retas

    你说的编辑器图标,我后面看看怎么优化下。
    dolphintwo
        53
    dolphintwo  
       2023-06-28 10:35:43 +08:00   ❤️ 1
    建议改标题:这是国内颜值最高的开源文档工具!
    ggp1ot2
        54
    ggp1ot2  
       2023-06-28 10:38:47 +08:00   ❤️ 1
    @star7th

    你要么看看,这个帖子里面大家的意见,同意你 [showdoc 是国内颜值最高的开源文档工具] 观点的有多少?

    要么再看看,获得感谢的回答是哪些?

    另外,我觉得别人否定你 [showdoc 是国内颜值最高的开源文档工具] ,是不需要像你说的,给个比你好的去证明

    你要 ui 上的建议,我也说了几点,让我觉得很丑的,现在又一定要别人去反证是完全多余的。

    用户觉得,不好看,就够了,就配不上 [颜值最高]

    就到这里吧。
    star7th
        55
    star7th  
    OP
       2023-06-28 10:39:09 +08:00
    @zhaol

    我没有不允许评价呀。我的意思是,如果反驳,最好能带上一些理据。比如说,你觉得 showdoc 不配国内同类开源文档的最高,那么就可以举一个反例反驳。
    我包括在评论区的回复,都是希望有理有据,而非只是发泄情绪。
    ggp1ot2
        56
    ggp1ot2  
       2023-06-28 10:41:41 +08:00   ❤️ 1
    另外,就颜值这个,限定开源、文档工具什么的,没啥意思。

    就是些 css 样式罢了,我说 typora 一些主题比你的好看 = 等价于我可以很快的做一个文档工具,复用那些主题。

    或者拿你的 showdoc 二开就换个主题,是不是就更好看了?

    都说到这里了,要不要考虑加个自定义 css 的模块?
    joooker
        57
    joooker  
       2023-06-28 10:43:11 +08:00
    u1s1 ,op 这个宣发文章是失败的,标题给人很大期待但实际可能有落差,并没有想象中的惊艳,建议下次起文案慎重。
    wangerka
        58
    wangerka  
       2023-06-28 10:45:17 +08:00   ❤️ 11
    看 OP 的历史发帖和其中的回帖,就是个标题党哗众取宠的🤡。上个帖子别人说字体丑,你硬是不接受。标题取得正常点会有这么多人挑刺?
    cnoder
        59
    cnoder  
       2023-06-28 10:46:10 +08:00   ❤️ 2
    小清新还行,颜值高谈不上。有种花哨但细节不行的感觉
    star7th
        60
    star7th  
    OP
       2023-06-28 10:50:15 +08:00
    @joooker

    @wangerka


    感觉这个标题似乎 招来了一些不友好的言论 。

    如果硬要从客观上看,本标题并没有脱离事实太多,因为国内开源文档工具很少,我在一个小众产品领域里说可能 [颜值] 最高,虽然不是非常离谱的乱说,但是也不算厚道谦虚,所以可能激起了某些人的反感情绪。

    所以我承认这个标题起得不算好了。下次不这样起标题了。

    后面的人就暂且不要从标题上讨论了,重点关注讨论下产品本身吧。
    fishily1993
        61
    fishily1993  
       2023-06-28 10:50:56 +08:00   ❤️ 8
    1. 风格挺简约的,我个人觉得很不错
    2. 广告法不允许宣传语当有“最好”,“第一”等词汇是有其正面意义的
    3. LZ 的情商也太低了😂
    GeekSuPro
        62
    GeekSuPro  
       2023-06-28 10:51:42 +08:00   ❤️ 2
    官网说到“超过 1 0 0 0 0 0 + 互联网团队正在使用 ShowDoc”,注意是团队,不是个人。真有这么多?为什么我之前都没听说过,还是我孤陋寡闻了
    divilbs
        63
    divilbs  
       2023-06-28 10:52:05 +08:00   ❤️ 6
    不敢苟同,就登录页的“反馈” btn 我就能笑一年
    littleBink
        64
    littleBink  
       2023-06-28 10:53:54 +08:00   ❤️ 3
    @star7th #55 对这类软件没有了解,但如果你调研过觉得这是国内同类开源文档颜值最高,那么只能说明是同类更加拉胯,而不是你的颜值高,菜鸡互啄属实没意思。大家点进来想看看天花板,结果发现就只是这样的水平,确实很失望。
    zzzzzzZ
        65
    zzzzzzZ  
       2023-06-28 10:54:34 +08:00
    非安利捧踩,陈述事实:
    我以前用 ShowDoc ,后面用 Obsidian 了
    star7th
        66
    star7th  
    OP
       2023-06-28 10:54:43 +08:00
    @ggp1ot2


    自定义 css 模块功能也是一个思路,后面看下有没有搞头。
    akring
        67
    akring  
       2023-06-28 10:55:26 +08:00
    提一个点,这个图标好像分辨率不够,在 4k 屏上是糊的

    https://p.ipic.vip/plfac2.png
    star7th
        68
    star7th  
    OP
       2023-06-28 10:56:32 +08:00
    @fishily1993
    @divilbs
    @grahamsa0503

    感觉这个标题似乎 招来了一些不友好的言论 。

    如果硬要从客观上看,本标题并没有脱离事实太多,因为国内开源文档工具很少,我在一个小众产品领域里说可能 [颜值] 最高,虽然不是非常离谱的乱说,但是也不算厚道谦虚,所以可能激起了某些人的反感情绪。

    所以我承认这个标题起得不算好了。下次不这样起标题了。

    后面的人就暂且不要从标题上讨论了,重点关注讨论下产品本身吧。
    Jynxio
        69
    Jynxio  
       2023-06-28 10:56:58 +08:00   ❤️ 2
    @star7th

    好的,这是你需要的论证:
    1.「 clean-jsdoc-theme 」是一个还不错 JSDoc 的开源主题,在 JSDoc 的帮助下可以直接根据代码注释来自动生成 API 文档,且该主题是互联网上随手找的。
    2.「 startlight 」是一个美观且全能的文档主题,在 Astro 的加持下,可以直接根据 markdown 来生成文档,并且有更好的 SEO 、更快的加载速度、美观的代码高亮、正确的 markdown 解析,还支持 MDX 和 RSS 更新;
    3.showdoc 本身的 UI 是有明显缺陷的,比如:代码类文字没有使用等宽字体、markdown 换行符解析有问题、大量直接暴露的链接、登录界面没有回退机制、首页图片模糊、页面不适配移动端、中英文之间缺少空白符、favicon 四角留白,showdoc 的样式设计是简陋的;
    4.如果你只想讨论国产+开源,那么请看 Apifox ,并且 GitHub 还有很多类似的产品;
    5.使用者更在乎好用 /易用,没那么在乎国产与否,比如哪怕 14 nm 是国产芯片的最高成熟制程(似乎),我也不会买来用,因为我可以选更好的舶来品;
    6.你不是来虚心请教的,你是来找认同的;

    链接:
    [clean-jsdoc-theme]( https://ankdev.me/clean-jsdoc-theme/v4/)
    [startlight]( https://starlight.astro.build/getting-started/)
    Jynxio
        70
    Jynxio  
       2023-06-28 11:00:01 +08:00
    @Jynxio 补充,如果只想当 XXX 领域第一,那么建议把前置条件收的再窄一点。
    star7th
        71
    star7th  
    OP
       2023-06-28 11:00:14 +08:00
    @GeekSuPro

    因为 showdoc 支持开源私有部署,所以很多数据我是无法追踪的。但是我从各方面的数据推测,包括 github 访问量,star 量,docker hub 下载量,阿里云镜像下载量,各方面推测是超过这个水平的。
    而且,这里的团队,没你想的那么大。大部分情况下就是某公司里的某几个技术小组团队在用。整个公司在用的情况不多,还是局限技术团队里。
    star7th
        72
    star7th  
    OP
       2023-06-28 11:06:46 +08:00
    @Jynxio

    感觉这个标题似乎 招来了一些不友好的言论 。

    如果硬要从客观上看,本标题并没有脱离事实太多,因为国内开源文档工具很少,我在一个小众产品领域里说可能 [颜值] 最高,虽然不是非常离谱的乱说,但是也不算厚道谦虚,所以可能激起了某些人的反感情绪。

    所以我承认这个标题起得不算好了。下次不这样起标题了。

    后面的人就暂且不要从标题上讨论了,重点关注讨论下产品本身吧。
    Jynxio
        73
    Jynxio  
       2023-06-28 11:14:12 +08:00
    @star7th
    “如果硬要从客观上看,本标题并没有脱离事实太多”

    -> 请让我说得再直白一些吧!<b>你的标题完全违背了事实</b>。如果你不愿意大方承认这一点,而是想要跳过这个问题,那么后面的人还会继续讲。
    sarices
        74
    sarices  
       2023-06-28 11:14:32 +08:00
    找个设计师设计一下吧,字体、图标尺寸比例不对
    Musong
        75
    Musong  
       2023-06-28 11:15:36 +08:00
    挺好看的,我个人不太理解开发喜欢的常见于技术博客的那种 高对比度大片文字简单排版 类似书籍的一类样式
    这个我个人比较喜欢,楼里的那个 gatsby-theme-antv 我也比较喜欢

    对于标题,打个比方,一个人说“我好丑”,就会引来安慰鼓励肯定,他说“我好美”,也必然会引来贬低、嘲讽
    客观么?理性么?大多数人所评价的最终会归结导这个人的表达,而不是他本身。
    这就是我对人类在任何体制、任何价值观、任何环境下都不抱希望的原因(跑题了哈哈)
    Myprajna
        76
    Myprajna  
       2023-06-28 11:17:16 +08:00   ❤️ 1
    对比度有点低,设计师总喜欢弄的浅浅的,觉得很有美感。我觉得有点累眼睛。代码块背景可以再黑一点。
    可以用 edge 的 F12 的 lighthouse 测一下,代码块那个对比度不够。
    [url=https://smms.app/image/KE9kibhepmO4aFU][img]https://vip2.loli.io/2023/06/28/KE9kibhepmO4aFU.png[/img][/url]
    n18255447846
        77
    n18255447846  
       2023-06-28 11:19:02 +08:00
    一般,程序员最重实用性
    n18255447846
        78
    n18255447846  
       2023-06-28 11:19:56 +08:00
    还有,每个人审美观念不一样,你标题....
    star7th
        79
    star7th  
    OP
       2023-06-28 11:21:23 +08:00
    @Jynxio

    没有完全违背的。因为原标题是取巧地说了“可能”两个字,既然说了可能,那解释空间就大了,你很难反驳 “可能” 这两个字是完全违背事实。
    我承认的是这种取巧不对,在一个小众领域里挖这种博眼球的标题没意思。我本想着吸引一些流量,但是现在看来那种负面流量要来没啥用。
    你没必要抓着我这一点不放。showdoc 都开源运营 7 年了,很多时候都是低调做事。这次觉得有必要宣传一下,所以才起了个博眼球的标题。我并不是投机取巧的人,因为投机取巧的人是沉不下心来做那么多年的。
    你就没必要抓着我这次 宣发失误 来较真下去了。
    pengtikui
        80
    pengtikui  
       2023-06-28 11:22:13 +08:00
    这个根本就算不上有颜值,所以也就不存在颜值高不高的问题了
    star7th
        81
    star7th  
    OP
       2023-06-28 11:28:12 +08:00
    @Musong

    说 “在任何体制、任何价值观、任何环境下都不抱希望” 这就悲观了哇。其实怎么说呢,主要是这标题起得有点容易招人反感。下次不这么取标题。 抛开标题来说,正文还是中规中矩的。
    star7th
        82
    star7th  
    OP
       2023-06-28 11:29:16 +08:00
    @n18255447846

    实用性还是有一点的。showdoc 毕竟都开源运营 7 年了。不过这标题确实容易招仇恨,下次不这么起标题了
    zsc8917zsc
        83
    zsc8917zsc  
       2023-06-28 11:31:03 +08:00
    用过 showdoc ,确实比较方便。感谢一下作者。
    另外,广告法一般禁止使用最高级的表达方式~
    deplivesb
        84
    deplivesb  
       2023-06-28 11:31:22 +08:00   ❤️ 8
    你管这个就叫颜值最高?被喷了就各种定语?只要定语足够多就能是第一是吧
    你的颜值最高就是官网 demo 中 只能放大不能缩小是吧
    你的颜值最高就是 icon 都是随便截图来的,四角白边都没处理的是吧
    你的颜值最高就是侧边目录展开跟狗屎一样的宽度是吧

    给你个建议,做开源不是靠嘴巴,别跟娱乐圈学,踏实一点吧。自己标榜 ‘国内’ 颜值最高。那你就非要在瘸子里面做将军,就自以为将军了?
    woqujjfly
        85
    woqujjfly  
       2023-06-28 11:37:46 +08:00
    网站的示例图可以优化一下 , 在我屏幕上感觉很模糊的感觉 ,还有登录界面的阴影都有种模糊老旧的感觉
    star7th
        86
    star7th  
    OP
       2023-06-28 11:39:35 +08:00
    @zsc8917zsc

    下次不这么其标题了哈,确实被很多人吐槽了
    star7th
        87
    star7th  
    OP
       2023-06-28 11:45:36 +08:00
    @deplivesb

    我这里是可以放大再缩小的,不清楚你那里为什么不能。不过你不是第一个反馈这个问题的,我晚点看看哪里是不是有 bug 。

    标题栏的图标,我是故意放四角白边的,这样辨识度高一点。

    你说的侧边栏目录展开,这个你是放大后再展开,这里的功能用得少,确实没注意到。不放大的目录树,或者移动端的目录展开,是很好的。我后面优化下。

    对于开源的态度,我确实同意你说的,要踏实一点。所以我踏实维护 showdoc 开源项目 7 年了。这次就是宣发的时候,标题党了一点,但正文还是正常的。你就没必要死抓着不放了。
    CoderLife
        88
    CoderLife  
       2023-06-28 11:46:27 +08:00
    颜值最高?
    star7th
        89
    star7th  
    OP
       2023-06-28 11:46:36 +08:00
    @woqujjfly

    登陆界面忘记更新了,还是很古老的版本,晚点弄一下。
    star7th
        90
    star7th  
    OP
       2023-06-28 11:47:35 +08:00
    @CoderLife

    感觉这个标题似乎 招来了一些不友好的言论 。

    如果硬要从客观上看,本标题并没有脱离事实太多,因为国内开源文档工具很少,我在一个小众产品领域里说可能 [颜值] 最高,虽然不是非常离谱的乱说,但是也不算厚道谦虚,所以可能激起了某些人的反感情绪。

    所以我承认这个标题起得不算好了。下次不这样起标题了。

    后面的人就暂且不要从标题上讨论了,重点关注讨论下产品本身吧。
    je11yfish
        91
    je11yfish  
       2023-06-28 11:57:02 +08:00
    爬完楼就一个感觉: 就这 UI ?最佳?
    BTW ,对于意见,OP 的反馈中没有一条是真的接受的,注意,我用了“真的”,就像 OP 用了“可能”。
    Ansen
        92
    Ansen  
       2023-06-28 11:59:38 +08:00
    一直在用,感谢楼主的开源

    楼主有时间可以用用飞书的知识库,我们团队用了感觉挺好用的
    Shawnan
        93
    Shawnan  
       2023-06-28 12:00:42 +08:00 via Android
    之前用过,还可以。UI 确实可以更美化一点
    star7th
        94
    star7th  
    OP
       2023-06-28 12:06:54 +08:00
    @je11yfish

    26 楼 ,33 楼,57 楼 的反馈我是 真的接受。因为他们有理有据,且情绪稳定温和。
    star7th
        95
    star7th  
    OP
       2023-06-28 12:07:58 +08:00
    @Ansen

    我也参考下飞书
    star7th
        96
    star7th  
    OP
       2023-06-28 12:10:47 +08:00
    @mydingyan

    回头看了下,忘记了回复这个问题。其实 app 端使用的用户少,我都比较少关注了。我记得 安卓端 app 是 ok 的,找个时间兼容测试下。
    dandycheung
        97
    dandycheung  
       2023-06-28 12:18:23 +08:00 via Android
    审美虽然主观上各有偏好,但大体上大家应该还是有共同感觉的。ShowDoc 我之前见过其它同事的小组在用,我自己选择时,看了一眼就放弃了,恐怕就跟楼主自己比较认可的“颜值”有很大关系。我后来甚至宁可自己 fork 一个叫 MinDoc 的项目去改进,只不过这几年需求不明显了,没有特别持续。
    96
        98
    96  
       2023-06-28 12:23:01 +08:00
    我觉得挺好看的,尤其对比其他家的。。。

    虽然现在是用的 git+md 文件做的接口文档,但是刚参加工作的时候确实用了很久的 showdoc 。给了一些小建议,因为有点多,所以放在 showdoc 的文档里了。https://www.showdoc.com.cn/improvement/
    securityCoding
        99
    securityCoding  
       2023-06-28 12:35:53 +08:00
    于我而言任何 api 文档都比不上 pb 来得简洁 233
    deplivesb
        100
    deplivesb  
       2023-06-28 12:39:26 +08:00
    @star7th #85 问题还是有的,主要我是第一次知道,打开 demo 看了不到 5 分钟就发现了这些问题,所以对我来说着实算不上最好。还是需要在斜街上继续打磨。我 82 楼的发言现在看起来好像也有点不太友好。望见谅。也祝愿你能坚持下去。给国内开源提供一份正向的力量。
    1  2  3  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   3132 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 44ms · UTC 05:00 · PVG 13:00 · LAX 21:00 · JFK 00:00
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.