V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
hbc
V2EX  ›  问与答

大家认为怎样的文档才是一个好的文档?

  •  
  •   hbc · 2011-10-22 17:36:10 +08:00 · 4772 次点击
    这是一个创建于 4784 天前的主题,其中的信息可能已经有所发展或是发生改变。
    我觉得无论是英文还是中文文档,最重要的是清晰和简洁。

    pocoo[0] 的文档就是一个很好的例子。

    另外有些文档大而全,但是看起来不着边际,入门很难;但是当你认真去斟酌其字字句句之后会醍醐灌顶,大有收获。

    sqlalchemy[1] 就是这类的典型代表。

    不知道各位认为怎样去写、翻译文档才是最好的呢?

    [0] http://flask.pocoo.org/
    [1] http://www.sqlalchemy.org/docs/
    3 条回复    1970-01-01 08:00:00 +08:00
    Livid
        1
    Livid  
    MOD
       2011-10-22 17:43:03 +08:00
    iOS SDK 的文档也很不错。

    * 组织得很有条理
    * 有适当的配图
    * 没有废话

    http://developer.apple.com/library/ios/navigation/
    hbc
        2
    hbc  
    OP
       2011-10-22 17:49:25 +08:00
    @Livid 没有废话这点异常赞同,在看 Dive into HTML5 将近全书完毕的时候,最终还是忍受不住作者那种罗嗦的口吻,而放弃继续阅读剩下的几个章节了。
    flyingkid
        3
    flyingkid  
       2011-10-22 18:04:07 +08:00
    google的帮助中心。

    m$

    mozilla
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   3022 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 21ms · UTC 14:40 · PVG 22:40 · LAX 06:40 · JFK 09:40
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.