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

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

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

    地址

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

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

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

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

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

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

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

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

    runapi 无法同步历史 showdoc 项目到客户端,因为历史上使用 markdown 编写,不是结构化数据,转不回来。但是从 runapi 创建的项目都可以自动生成文档到 showdoc
    star7th
        38
    star7th  
    OP
       107 天前
    @u21t20o15

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

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

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

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

    至于说配色的问题,我后面会咨询设计师意见,后面再做个更完善的版本。
    star7th
        42
    star7th  
    OP
       107 天前
    @geekboy

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

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

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

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