-
目的:
-
帮助编辑们理解如何将作者们创作的内容合并到《Steem指南》中
-
保证《Steem指南》全书的格式正确、内容质量高
-
-
角色:
-
作者(Author):创作和分享《Steem指南》的内容
-
编辑(Editor):审阅作者发布的内容,并提交到《Steem指南》的源代码
-
项目维护者(Maintainer):审阅编辑提交的内容,并合并到《Steem指南》在线版本
-
第2版修订内容
- 由于目前图片会自动下载并自动更新Markdown,省去了第1版中介绍的如何上传图片和修改路径的步骤。
- 添加了编辑时需要注意的文章标题、Markdown标题语法、steempress投稿等问题的处理方法。
编辑审核流程
- 审阅
- 编辑
- 检查/修复
- 发布
#1 审阅
我们目前采用每周修订一章的策略,细水长流,并减少编辑的工作量。
所以,编辑主要是对本周获得的稿件进行审阅。
-
查看投稿:每周的修订工作开始后,编辑可以在页面 https://busy.org/created/steem-guides 查看最新给steem-guides的投稿。
-
审阅稿件:对于每一篇投稿,编辑需要对内容进行审查,并回复相应的修改建议、或提出疑问;确保稿件的最终内容满足要求、格式符合写作规范,并确实能够使得读者受益。对于通过了审阅的文章,编辑需要回复作者审核已经通过,即将提交。
#2 编辑
对于通过审阅的作者投稿,需要把他们合并到书籍当中。我们的书籍的源代码在GitHub仓库:https://github.com/steem-guides/steemh
下面是编辑的流程:
(1) 找到对应文件:比如第二章,对应的文件就是02_0.Rmd,点击打开文件 https://github.com/steem-guides/steemh/blob/master/02_0.Rmd 我们可以看到该章节的markdown源代码。
(2)添加作者的稿件:点击右侧的编辑按钮(笔的图标),进入到编辑页面:https://github.com/steem-guides/steemh/edit/master/02_0.Rmd
用steemd查看稿件的markdown源码,比如https://steemd.com/github/@evathinking/github(将页面连接中的steemit.com替换成steemd.com,即 it -> d)。注意:这里只是做例子,并非真的要编辑此文。
将steemd中的markdown源码,复制到GitHub中对应的章节。
需要注意的是,有一些地方需要做一些修改和替换:
- 需要给章节写一个标题,并添加作者、编辑、原文链接等信息,如
“\## 如何参与dapeng《Steemit 教程》Github多人写作 ^[作者:\
,编辑:\
,原文链接:https://steemit.com/github/@evathinking/github] ”;
- @字符在RMarkdown(.Rmd)文件中需要用\@来表示(@前加反斜杠);
- 如果文章中使用了 \##、\####等标题语法,在文章中需要替换成加粗语法(\** 标题 \**),否则在书籍的标题中会显示太多层级;
- 如果作者是用steempress投稿,源代码主要是html格式,需要使用html转换为markdown的在线工具(如https://www.browserling.com/tools/html-to-markdown),将提交的格式统一为markdown以便后期维护。
- 补充说明:在前一个版本中,编辑需要手动将图片上传到images文件夹中。在本版本中我们改进了该步骤,图片会被自动下载,并替换成本地的图片链接,所以在编译PDF时并不会出错。
(3)对比修改:点击顶部的Preview changes按钮,可以和前一个版本对比修改的文本,可以看到新增或删除的文字,查看格式是否正确。
(4)提交Pull Request:修改和预览完成后,可以滚动到页面的最底部,提交一个Commit(一次贡献),添加本次提交的基本说明(如修订第2章),然后选择Create a new branch,在下面的branch名称中输入(章节+日期,如chapter2-2019-0419)。点击Commit changes按钮。
随后会进入到Pull Request的页面,比如https://github.com/steem-guides/steemh/compare/master...chapter2-2019-0419?quick_pull=1。一般不需要修改,点击“Create pull request”创建Pull Request
随后一个Pull Request就会被创建了:https://github.com/steem-guides/steemh/pull/10
至此,一个Pull Request创建成功了,如果Pull Request被Merge(合并)到master branch中,书籍就会被自动编译和发布。
#3 检查/修复
Pull Request创建成功以后,编辑的大部分工作都已经完成了,但还有几项工作需要关注:
(1) 查看书籍编译结果:查看新提交的源码的自动编译的结果,是否出现错误。如果出错就没法合并了,如下图所示:
如果遇到编译失败的情况,请参考第1版中关于修复的相关内容进行修复。
通过最近的一次改进,目前提交的Markdown中的图片链接会采取自动下载并自动更新Markdown的策略,由图片缺失而编译失败的可能性大大降低,所以本次编译直接通过了。编译成功时,在Pull Request的页面会显示绿色的勾。
(2) 审查在线书籍:提交完成后,如果没有格式等问题,编译和预发布会成功,但我们需要继续做一些审查。
这时,我们可以打开预发布的书籍链接(不是正式发布的地址,末尾有-staging后缀): https://steem-guides.github.io/steemh-staging
并查看最新编辑的书籍内容是否可以看到了,以及pdf/epub等格式是否可以提供下载了:
由此我们可以看到,我们再上面添加的内容已经成功部署了,但存在几个问题:
-
2.15小节不应该是第2章的内容,我们应该把它放到正确的章节。
-
图片的下方显示了图片的标题,但并没有表达合适的意义,我们应该在编辑RMarkdown时输入合适的图片说明,或者不提供说明。也就是说, 中,1.png应该换成更有意义的文字,或者删除。
如果要继续修改,我们可以返回上一步的过程继续编辑。如果基本满意,那么编辑的工作就到此大功告成了,恭喜!:)
#4 发布
最后一步,将最新的改动发布到《Steem指南》的在线版本:https://steem-guides.github.io/steemh/
编辑在工作完成后,通知GitHub项目的维护者(Maintainer)已经提交了Pull Request并预发布成功。维护者检查编译和预发布没有问题后,将点击Merge pull request按钮,将当前的Pull Request的代码合并到master branch(主分支)。
合并完成后,对于最新版本书籍的编译和发布将自动触发,将书籍发布到https://steem-guides.github.io/steemh/,并提供pdf和epub的下载。
恭喜所有参与者,至此创作、编辑和合并的工作已经完成了!
最后
本文适用于《Steem指南》的编辑阅读,也方便其他读者了解《Steem指南》的编写工作是如何完成的。
如果你对研究攻略、帮助新人、制作书籍有兴趣,欢迎加入《Steem指南》编辑部,一起学习和分享关于Steem的知识。
Posted from my blog with SteemPress : http://cnstm.org/team-cn/2019/04/19/%e3%80%8asteem%e6%8c%87%e5%8d%97%e3%80%8b-%e7%bc%96%e8%be%91%e7%9a%84%e5%b7%a5%e4%bd%9c%e6%b5%81-editors-workflow-%e7%ac%ac2%e7%89%88-2019-04-19%e6%9b%b4%e6%96%b0/
本图由 @maiyude 设计
文档介绍