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

ShowDoc v3.0 发布 , 提升了产品颜值和操作体验,但是设计师说——

  •  
  •   star7th · 2023-02-14 10:18:50 +08:00 · 3990 次点击
    这是一个创建于 408 天前的主题,其中的信息可能已经有所发展或是发生改变。

    地址

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

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

    开发小故事

    在年前,设计师基本为 showdoc 设计出了一套 ui 主题。然而直到昨天,我才按设计稿重构了一版 UI 。虽然外观看着变化也不算非常大,但实际上底层代码已重构掉了一半,很多产品逻辑导致的底层组件封装方式发生了变化,同时我也借此机会修复了历史上不少代码的遗留包袱。

    到现在,完成度还没有很高,很多细节没打磨好,大约只达到设计稿原意的六七成。我决定直接先发布一个 3.0 版,后面的问题后面完善。

    设计师说,我习惯一步到位,做完善了再上。

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

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

    尽管这个观点不同,但是我非常欣赏设计师的产品思维和对细节的追求。后续也继续有意愿跟他合作其他产品。

    3.0 版本更新了什么

    重写了 UI 和交互逻辑,大大提升了视觉效果和操作体验,包括但不限于以下内容:

    • 展示多个项目时候采用列表结构,同时完善项目分组功能,适合更多项目的场景
    • 大部分打开新页面的操作,如用户中心、目录管理、团队管理等等,都改为当前页面弹窗的形式,方便关闭弹窗后无感回到之前的操作,避免割裂感。
    • 完善拖放组件,涉及到拖放的场景,比如项目分组的拖放、页面排序的拖放、目录管理的拖放,都统一元素高度和样式。
    • 调整项目展示页的布局,包括常规多页项目、单页项目和表格展示项目,增加统一的 header 和图标样式。
    • 调整功能按钮的展示与收起逻辑,在便捷和简洁间取得平衡。

    给新用户看的 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

    相关截图

    ShowDoc v3.0.0 发布 ,  提升了产品颜值和操作体验,但是设计师说——

    ShowDoc v3.0.0 发布 ,  提升了产品颜值和操作体验,但是设计师说——

    ShowDoc v3.0.0 发布 ,  提升了产品颜值和操作体验,但是设计师说——

    ShowDoc v3.0.0 发布 ,  提升了产品颜值和操作体验,但是设计师说——

    48 条回复    2023-02-18 23:18:12 +08:00
    ieliwb
        1
    ieliwb  
       2023-02-14 11:12:32 +08:00
    正在用,支持
    highf4324
        2
    highf4324  
       2023-02-14 12:28:51 +08:00
    很不错,不过还是建议首页左上角的 LOGO 不要用 PNG/JPEG 图像,因为看起来有点模糊。
    建议直接用 svg ,这样无论怎样都不会模糊。
    yushiro
        3
    yushiro  
       2023-02-14 12:30:32 +08:00 via iPhone
    showdoc 是换域名了吗?用之前保存的 url 都没法正常显示了
    superliwei
        4
    superliwei  
       2023-02-14 12:42:19 +08:00
    👍 非常棒~!
    star7th
        5
    star7th  
    OP
       2023-02-14 13:02:49 +08:00
    @highf4324 主要是因为当初这个原始 logo 我没有保存源文件。只有一张大图。不过我倒可以使用大图生成各种分辨率的。所以你说的模糊问题,我尝试换个大分辨率一点的图标
    star7th
        6
    star7th  
    OP
       2023-02-14 13:03:48 +08:00
    @yushiro showdoc 官网域名是 https://www.showdoc.com.cn/ ,我不清楚你以前是否使用了非官方平台(即别人搭建开源版给他自己用的,而你跑去注册账号了)
    akiyamamio
        7
    akiyamamio  
       2023-02-14 13:04:13 +08:00
    开源版和商业版有啥区别?
    star7th
        8
    star7th  
    OP
       2023-02-14 13:04:15 +08:00
    @superliwei
    @ieliwb
    谢谢支持
    star7th
        9
    star7th  
    OP
       2023-02-14 13:10:03 +08:00
    @akiyamamio 软件功能上的区别很小,可以忽略。

    商业版主要是方便一些不想动手搭建的用户,更重要的是他们觉得数据交给 showdoc 官方去维护,比自己搭建的更可靠。尤其企业用户对数据的稳定性要求更高。如果是私自搭建开源版,服务器运维要你自己去保证可靠性。
    yushiro
        10
    yushiro  
       2023-02-14 13:42:43 +08:00 via iPhone
    并不是用的其他人的,域名就是 showdoc.com.cn ,现在访问还是有问题,会去链接 dyfun-spare2.showdoc.这 com.cn:8888 这个地址,返回全部超时
    polarbearn
        11
    polarbearn  
       2023-02-14 14:00:47 +08:00
    从文档跳转到登录界面,会造成页面假死
    刚刚提的 issues
    github.com/star7th/showdoc/issues/1851
    EngAPI
        12
    EngAPI  
       2023-02-14 14:08:18 +08:00
    用了你们推送半年多,感谢
    mydingyan
        13
    mydingyan  
       2023-02-14 14:28:14 +08:00
    刚使用./showdoc update 命令升级了, 发现数据都被清空了, 应该怎么操作下
    star7th
        14
    star7th  
    OP
       2023-02-14 14:52:17 +08:00
    @yushiro

    dyfun-spare2.showdoc 是我们自建的 cdn 服务,你那边访问有问题吗?
    你是什么网络?如果是使用公司网络,会不会是公司安全限制了 8888 端口出口?能否用手机网络试一下?
    star7th
        15
    star7th  
    OP
       2023-02-14 14:52:37 +08:00
    @rolitter 好的,晚点修复下。
    star7th
        16
    star7th  
    OP
       2023-02-14 14:52:53 +08:00
    @EngAPI 多谢支持
    star7th
        17
    star7th  
    OP
       2023-02-14 14:58:14 +08:00
    @mydingyan
    可能是没有写入权限导致。在你目录 /showdoc_data 下应该能找到类似 html_bakxxxx 这样名字的文件夹。将它改掉,替换原来的 html 目录,然后重启下 docker 容器就好了
    lower
        18
    lower  
       2023-02-14 15:00:42 +08:00
    刚试了一下,8 年前的账号还能登录进去,当年的项目文档居然还都在😂
    pengtdyd
        19
    pengtdyd  
       2023-02-14 15:02:19 +08:00
    好奇,showdoc 开源项目商业化能赚到钱吗?本身就是很小众的产品
    star7th
        20
    star7th  
    OP
       2023-02-14 15:03:56 +08:00
    @lower 嗯,多年来的账号没清理过。顶多清理下系统生成的示例文档, 但用户创建的数据没动。
    star7th
        21
    star7th  
    OP
       2023-02-14 15:06:20 +08:00
    @pengtdyd

    能的。其实 api 以及文档市场没有你想象中的小众。甚至说这个领域并不小众,只是说我占据的市场份额小。
    mydingyan
        22
    mydingyan  
       2023-02-14 15:13:07 +08:00
    @star7th
    感谢,使用上述方法覆盖后重新升级正常。UI 变化挺大,体验下~
    yushiro
        23
    yushiro  
       2023-02-14 16:34:48 +08:00 via iPhone
    嗯,在 ping.sx 上看了一下,这个域名+端口,国外访问国内全部 timeout ,只能国内访问。
    公司出口正好是 hk 的……
    star7th
        24
    star7th  
    OP
       2023-02-14 16:51:20 +08:00
    @yushiro

    额。那应该是我们的 ip 库定位有差异。如果是非中国的 ip ,我们会转向国外节点。你这样,你用个代理先临时访问,用大陆内或者美国代理都行,我们后面修正下对香港的 ip 库记录。
    Psily1017
        25
    Psily1017  
       2023-02-14 17:12:22 +08:00
    支持,刚毕业就接触到 showdoc ,从 1.0 用到了 3.0 ,肉眼可见的 ui 设计变得越来越漂亮和功能逻辑变得实用。
    star7th
        26
    star7th  
    OP
       2023-02-14 17:38:08 +08:00
    @Psily1017

    1.0 的版本,那确实有好几年了。
    siknet
        27
    siknet  
       2023-02-14 17:57:34 +08:00
    模板风格开发方便吗?
    yushiro
        28
    yushiro  
       2023-02-14 18:13:52 +08:00 via iPhone
    @star7th 我就是用了代理才发现可以访问,前几个月想用来着,结果发现 UI 全是乱的,我以为公司跑路了呢
    star7th
        29
    star7th  
    OP
       2023-02-14 18:35:04 +08:00
    @siknet 挺不方便的,因为 showdoc 看起来简单,但其实有很多很多细节。很多细节没有从一开始做成变量或者方便批量切换,所以要做在运行时换一套模板或者皮肤都不容易。而且我觉得嘛,模板不是刚需,可以暂时不用花精力。
    star7th
        30
    star7th  
    OP
       2023-02-14 20:20:44 +08:00
    @yushiro
    我找了挺多香港 ip 来做测试,ip 库都显示正确。像你的那种情况,应该是因为 ip 被识别为大陆内地了——但实际网络是香港,所以才有这个问题。我估计应该是特例,因为我测试其他香港 ipi 都是正常的。
    如果方便的话你可以把 ip 段告诉我下。或者你就针对 showdoc 使用代理访问吧。
    815979670
        31
    815979670  
       2023-02-14 20:33:15 +08:00
    问一下 showdoc 商业版的数据库也是 sqlite 吗?还是换了 MySQL 之类的?
    star7th
        32
    star7th  
    OP
       2023-02-14 20:36:16 +08:00
    @815979670

    官网的并发,sqlite 肯定扛不住的。用了 mysql 和 redis 。
    star7th
        33
    star7th  
    OP
       2023-02-14 20:37:48 +08:00
    @815979670 实际上官网版跟开源版,很多数据库结构都不一样了。官网版我都是单独维护的。
    dcsite
        34
    dcsite  
       2023-02-15 09:16:37 +08:00
    说实说,这个 UI 一如既往的难看…… 要是出个 GITBOOK 的主题就好了。
    star7th
        35
    star7th  
    OP
       2023-02-15 09:23:03 +08:00
    @dcsite
    说实话,gitbook 当然不难看,但是如果将它封为效仿的标准,感觉就不是很有必要,因为是两种风格不一样的产品。
    我推出 3.0 版后,除了你,没有一个人说难看的。最多就是说细节没到位,还可以完善,但远谈不上难看。
    u21t20o15
        36
    u21t20o15  
       2023-02-15 09:46:41 +08:00
    希望可以做到自动化生成接口文档到私有部署的 showdoc ,然后 RunApi 能同步私有部署的 showdoc 接口数据进行本地化调试,提升开发效率。
    目前在用 Apidoc 插件(注解生成接口文档)和 Yapi ,但是 yapi 不能保存调试的参数,每次都要重新写请求参数
    star7th
        37
    star7th  
    OP
       2023-02-15 09:55:04 +08:00
    @u21t20o15

    RunApi 已经可以做到自动化生成接口文档到私有部署的 showdoc https://www.showdoc.com.cn/runapi

    runapi 无法同步历史 showdoc 项目到客户端,因为历史上使用 markdown 编写,不是结构化数据,转不回来。但是从 runapi 创建的项目都可以自动生成文档到 showdoc
    star7th
        38
    star7th  
    OP
       2023-02-15 09:57:43 +08:00
    @u21t20o15

    如果你要用注解生成 api 的话,可以参考这里
    https://www.showdoc.com.cn/page/741656402509783

    我推荐的做法是,注解生成 runapi 项目。而 runapi 项目会自动生产 showdoc 项目。从而实现你说的需求,即:
    可以注释生成文档,并且生成的接口在 runapi 可以调试
    CaffreySun
        39
    CaffreySun  
       2023-02-15 09:59:03 +08:00
    我也在用 ShowDoc ,我觉得问题不是出在 UI 难看上,而是排版和配色上,说白了就是没有 gitbook 可读性强,
    gitbook 将大片显示区域留给内容,内容两侧有大片空白,目录位于最右侧,在看内容时视觉上没有干扰。
    gitbook 整体字体更大更利于阅读。
    gitbook 排版细节更好,
    比如标题上边距大于下边距,从空间上就能知道这个标题是下面内容的标题
    再比如段落之间的间距要大于段落内行间距,从空间上很容易区分段落。
    还有就是配色问题,ShowDoc 整体配色颜色很多,显的有点凌乱
    geekboy
        40
    geekboy  
       2023-02-15 10:03:39 +08:00
    希望可以加上评论功能
    star7th
        41
    star7th  
    OP
       2023-02-15 10:06:42 +08:00
    @CaffreySun

    showdoc 没办法像 gitbook 那种将大片显示区域留给内容,因为两者面向的文档类型不一样。

    像 gitbook 这样的大片区域,非常适合文字段落饱满的情况,比如写一篇教程,文字或者代码非常饱满,可以充满一个个段落的。
    但是 showdoc 没办法,因为 showdoc 大部分用来解决 api 文档场景。写 api 文档,段落是不饱满的,我自己测试过,在锻炼不饱满的情况下,不同分辨率下的视觉效果无法统一,且都不算好看。
    至于说排版细节,那就确实是的,showdoc 有不少要改进的地方。但无论如何,都不能直接仿照 gitbook ,因为主要面向的文档类型不一样。

    至于说配色的问题,我后面会咨询设计师意见,后面再做个更完善的版本。
    star7th
        42
    star7th  
    OP
       2023-02-15 10:14:51 +08:00
    @geekboy

    评论需求是一个很模糊的需求。说需要嘛,这几年来用户的呼声不大。说不需要嘛,偶尔会有人说。https://github.com/star7th/showdoc/issues/553

    我自己依然没想好。再确认之前,我可能暂时先不动手做这个,因为评论功能会强势地占用视觉空间,并不是躲在一个二级菜单里等着用户使用就好。
    sairoa
        43
    sairoa  
       2023-02-15 12:08:22 +08:00
    代码块输入英文单引号会被转义,保存后页面显示为`'`。
    star7th
        44
    star7th  
    OP
       2023-02-15 12:20:21 +08:00
    @sairoa 昨天晚点的时候发布了 3.0.1 版,就是修复此问题的。你更新下。
    gongquanlin
        45
    gongquanlin  
       2023-02-15 21:24:23 +08:00   ❤️ 1
    用了好几年了,一直在用。牛逼,加油。什么时候能优化一下移动端就牛逼了,现在在手机上用 app 会有很多错位 /占满的问题
    star7th
        46
    star7th  
    OP
       2023-02-15 22:12:09 +08:00
    @gongquanlin

    移动端好久没更新了,因为用户少,大部分用户都是电脑上把 showdoc 当生产力工具使用。有空再看看移动端吧
    idragonet
        47
    idragonet  
       2023-02-18 20:25:02 +08:00
    3.0 怎么编辑框,有时候 ctrl+c 容易导致编辑框消失?
    star7th
        48
    star7th  
    OP
       2023-02-18 23:18:12 +08:00
    @idragonet

    去官网试一下 有没有这样的问题 https://www.showdoc.com.cn/ 如果官网没问题,那可能是开源版滞后。你需要更新一下。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3481 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 30ms · UTC 10:58 · PVG 18:58 · LAX 03:58 · JFK 06:58
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.