技术写作与文档2012developmentseed.org
Prose：一款面向 GitHub 的内容编辑器
Introducing Prose: A Content Editor for GitHub
导读
这篇介绍 Prose：一个基于 GitHub 的网页内容编辑器，可以直接在浏览器里编辑 Markdown 并提交到仓库。评论区延伸到 Markdown 之后的写作形态、内容与呈现分离，以及把编辑器嵌进现有发布流程的需求。对关心写作工具与发布工作流的写作者来说，这些讨论值得一读。
可以直接用的写作要点
- 01
Markdown 已是网页内容创作的事实标准；用纯文本标记写作，内容才能被版本管理、被多种工具复用。
- 02
把内容当数据、与呈现分离，同一份结构化文本才能可靠地输出 PDF、ePub 等多种格式。
- 03
好编辑器的价值在于降低“写作—提交—发布”的摩擦，让写作发生在内容真正存放的地方。
- 04
协作改稿可借鉴“补丁/建议”的思路：把修改建议与原文分开保存，而不是直接覆盖原文。
HN 评论精选
Markdown 之后的方向是语义化富文本：内容与呈现分离，结构化内容可复用到多种输出。
Markdown 是目前网页写作的事实标准，但下一步是什么？我认为答案很明确：语义化富文本编辑。也就是把内容当作数据，与呈现分离。难点在于做出能可靠地把纯文本与标注分开保存的网页工具；这类工具一旦成熟，就能支撑新一代协作写作应用，产出的结构化内容可被分析、可视化、转成 PDF、ePub 等任意格式，或接入其他应用。可以想象 Prose 提供实时的所见即所得，并用“补丁”的方式对某篇文档提出改进建议。
_mql查看英文原文
Using this thread to extend the discussion about digital content authoring... Prose relies on Markdown, the current de-facto standard for content authoring on the web. But what comes after? If you ask me the answer is clearly: Semantic Rich Text Editing. So if you like Prose, you might also like the idea of Substance, which is essentially about considering content as data and separating it from presentation. The challenging part here is to come up with web-based tools, that reliably maintain plaintext and annotations separately. Once these tools are ready, a new generation of application for collaborative content composition can be built. The resulting structured content is ready to be analyzed, visualized, turned into arbitrary output formats (PDF,ePub, …) or integrated with other applications. Imagine Prose, providing WYSIWYG editing in realtime, plus the concept of patches to suggest improvements to a particular document. Related links: - http://github.com/substance (see composer, surface, text as well as architecture and document repositories) - https://github.com/prose/prose/issues/139 So if (and only if) you like that idea, pls support our entry for the Knight News Challenge's data call. http://newschallenge.tumblr.com/post/25422992783/substance-towards-open-digital-publishing Or even better, start contributing! :) Thanks, Michael
写作者希望编辑与发布工具能直接嵌入现有应用，就地管理博客内容。
我很希望能把 Prose 和 Jekyll 作为 gem 直接放进 Rails 应用（比如一个标准的 SaaS 应用），用它来服务和管理应用的“关于/博客”页面。有类似的东西吗？
te_chris查看英文原文
I would LOVE to be able to drop this and jekyll into a rails app as a gem (say a standard SaaS app) and serve/manage the about/blog part of the app with this. Is there anything like that?
GitHub 工具生态在扩张，基于 git 的写作与发布方式会越来越重要。
界面非常漂亮。我注意到给 GitHub 加功能的趋势很合理——它已有数百万用户，很多人日常在用。我自己也在做一个 GitHub 相关项目（gitify.me，改进通知）。GitHub 及其工具生态会大幅增长，用 git 和 GitHub 会越来越重要。Prose 的前端架构很合理，应该用了代理来绕过 API 请求的同源限制；再加些服务端缓存来提速、减少对 GitHub 的请求也合理。
btipling查看英文原文
Wow, the UI on that is gorgeous. I noticed a trend to add features and capability to GitHub which makes a lot of sense because it must have something like millions of users by now and it's something many of here personally use. I'm also working on something for GitHub (a work in progress, http://gitify.me - better notifications). I think we're going to see a lot of growth in the ecosystem around GitHub and tools. Using git and GitHub is going to become more important as time passes by. For Prose, the front-end architecture makes a great deal of sense, and they must be using a proxy to get around same origin on API requests. I think some server side operations for caching might make sense to enable speed and reduce the number of requests on GitHub.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选