《Steem指南》 -- 编辑的工作流 | Editors' Workflow
-
目的:
-
帮助编辑们理解如何将作者们创作的内容合并到《Steem指南》中
-
保证《Steem指南》全书的格式正确、内容质量高
-
-
角色:
-
作者(Author):创作和分享《Steem指南》的内容
-
编辑(Editor):审阅作者发布的内容,并提交到《Steem指南》的源代码
-
项目维护者(Maintainer):审阅编辑提交的内容,并合并到《Steem指南》在线版本
-
编辑审核流程
-
审阅
-
编辑
-
修复
-
发布
#1 审阅
我们目前采用每周修订一章的策略,细水长流,并减少编辑的工作量。
所以,编辑主要是对本周获得的稿件进行审阅。
-
查看投稿:每周的修订工作开始后,编辑可以在页面 https://busy.org/created/steem-guides 查看最新给steem-guides的投稿。
-
审阅稿件:对于每一篇投稿,编辑需要对内容进行审查,并回复相应的修改建议、或提出疑问;确保稿件的最终内容满足要求、格式符合写作规范,并确实能够使得读者受益。对于通过了审阅的文章,编辑需要回复作者审核已经通过,即将提交。
#2 编辑
对于通过审阅的作者投稿,需要把他们合并到书籍当中。我们的书籍的源代码在GitHub仓库:https://github.com/steem-guides/steemh
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOBfOa6wHORHeJ-KoG%2Fimage.png?alt=media&token=2797cd84-b0cb-4d92-8dd0-9e35e78798d1)
下面是编辑的流程:
(1) 找到对应文件:比如第二章,对应的文件就是02_0.Rmd,点击打开文件 https://github.com/steem-guides/steemh/blob/master/02_0.Rmd 我们可以看到该章节的markdown源代码。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOCMWr75sfLn1jNmI8%2Fimage.png?alt=media&token=170f87ee-eb6a-4a4a-8ede-7693c32c9412)
(2)添加作者的稿件:点击右侧的编辑按钮(笔的图标),进入到编辑页面:https://github.com/steem-guides/steemh/edit/master/02_0.Rmd
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbODKPWGB_f19sDNila%2Fimage.png?alt=media&token=124ac76b-6946-4a40-b40c-30cb25714a10)
用steemd查看稿件的markdown源码,比如https://steemd.com/github/@evathinking/github(将页面连接中的steemit.com替换成steemd.com,即 it -> d)。注意:这里只是做例子,并非真的要编辑此文。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOF3f-WfHMDqVqsgXs%2Fimage.png?alt=media&token=d1263aeb-0647-42b1-8ceb-35b8df366e63)
将steemd中的markdown源码,复制到GitHub中对应的章节。
需要注意的是,有一些地方需要做一些替换:
-
@字符在RMarkdown(.Rmd)文件中需要用\@来表示(@前加反斜杠);
-
图片需要上传到images文件夹中。(建议等Pull Request创建以后再添加新的图片,下文会提到)
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOI3Ga6lkmmDXptHXT%2Fimage.png?alt=media&token=5a343d5e-0ccf-490d-9b03-d3c549957612)
(3)对比修改:点击顶部的Preview changes按钮,可以和前一个版本对比修改的文本,可以看到新增或删除的文字,查看格式是否正确。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOIkRPFmk3UqiBARfo%2Fimage.png?alt=media&token=9a868762-b314-43c9-aabc-faeda593b76b)
(4)提交Pull Request:修改和预览完成后,可以滚动到页面的最底部,提交一个Commit(一次贡献),添加本次提交的基本说明(如修订第2章),然后选择Create a new branch,在下面的branch名称中输入(章节+日期,如chapter2-2019-0401)。点击Commit changes按钮。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOJgxe-7M2ZeQmZ4l2%2Fimage.png?alt=media&token=f15504fb-ae40-4284-aec7-7b31dd422742)
随后会进入到Pull Request的页面,比如https://github.com/steem-guides/steemh/compare/master...chapter2-2019-0401?quick_pull=1。一般不需要修改,点击“Create pull request”创建Pull Request
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOKSQswEKYT4mxKNb-%2Fimage.png?alt=media&token=f9961806-ce01-437a-b3e0-719c4fd2e693)
随后一个Pull Request就会被创建了:https://github.com/steem-guides/steemh/pull/5
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOL7sDtiNVm0SkCuAL%2Fimage.png?alt=media&token=892066c0-5236-4f3f-b929-98749eb4332c)
至此,一个Pull Request创建成功了,如果Pull Request被Merge(合并)到master branch中,书籍就会被自动编译和发布。
#3 修复
Pull Request创建成功以后,编辑的大部分工作都已经完成了,但还有几项工作需要关注:
(1) 查看书籍编译结果:查看新提交的源码的自动编译的结果,是否出现错误。如果出错就没法合并了,如下图所示:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbOMk3vyE3lqAT7uGEF%2Fimage.png?alt=media&token=8b2c6f63-54a2-47a4-bfc3-7308ffd3ff97)
可以看到出错原因是图片没有存到本地:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOPqtAy-qzdnVjJAgp%2F-LbONXL1Hms_tZG83B-H%2Fimage.png?alt=media&token=21889c1e-d7e3-42f1-90bb-bcc9773b3598)
(2) 继续修改:如果有图片要上传或者其他文本要修改,我们也可以在这个阶段进行;
比如上面的错误告诉我们图片没有上传,我们继续上传图片。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOYAE0m4KYWSZb3F-9%2F-LbOYpAmA-M8u1-SOcaG%2Fimage.png?alt=media&token=0fd68413-20d7-4129-b306-d1ac1f8e018c)
点击标题下方的branch的名称(此处是chapter2-2019-0401),进入到branch的页面:https://github.com/steem-guides/steemh/tree/chapter2-2019-0401
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOYAE0m4KYWSZb3F-9%2F-LbOZ9cNNa5_KcwRdkX3%2Fimage.png?alt=media&token=6229a2f7-65e4-4dd0-a7ee-6e72db1bc80c)
然后点击images文件夹,进入文件夹的页面:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOYAE0m4KYWSZb3F-9%2F-LbOZRHceyXC1HABV6Tx%2Fimage.png?alt=media&token=16ade90e-eaf9-4641-b560-2af9eae89c40)
将刚才没有上传的图片文件从steemit下载,并且按照“章节-内容-编号”的格式命名,比如:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOhtz4BTKj9qYYny7K%2Fimage.png?alt=media&token=d7817371-f337-4d97-8fad-7cad61c23c18)
点击Upload files按钮,在页面中上传上面的图片
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOYAE0m4KYWSZb3F-9%2F-LbO_Czfmd1jImT_rn74%2Fimage.png?alt=media&token=089d457e-4908-44cc-b423-a4850c79c3b9)
上传成功后,添加注释(如第2章修订:上传图片),说明修改的内容。选择commit directly to the XXXX branch,点击Commit changes按钮。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOiW-R8Zlo_Sw7Dsq9%2Fimage.png?alt=media&token=6556da16-d273-4954-b57f-d8192a57e28a)
完成后会回到branch的页面,继续选择章节的RMarkdown文件(.Rmd),如02_0.Rmd。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOjclnTG4Mg98BKk01%2Fimage.png?alt=media&token=10e7351b-c910-429b-b16f-d5dbda8b0ae7)
编辑02_0.Rmd文件(编辑方法同上面提到过的一样),修改图片的链接,为刚才上传的文件的相对路径,如下图所示:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOkWDXXARAKY8o2TG0%2Fimage.png?alt=media&token=b7a61ce8-f898-48a2-b257-f0735a267203)
点击Commit changes按钮,再次提交02_0.Rmd文件。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOl3ScrLgvUv9hEezr%2Fimage.png?alt=media&token=2d224865-6097-4f62-8a19-43b2feff6ff6)
修改提交完毕,点击<>Code这个标签,回到文件夹的首页。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOluF2P4JxWmtFTj25%2Fimage.png?alt=media&token=7946bd15-4a4d-4f8d-bc27-fc9658bcba33)
然后点击上面的View #5(或其他数字)链接,可以回到我们之前创建的Pull Request:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOm40XwTmAzejLg7dW%2Fimage.png?alt=media&token=0e151f76-44e4-4d81-a383-a73154d2371a)
接下来,我们需要等待编译和部署的任务自动完成(大约5分钟)。如果编译成功(绿色),我们则进入到下一步;否则,我们需要继续修改RMarkdown文件,修复潜在的问题。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOmd-bvkltarrM6FGI%2Fimage.png?alt=media&token=afe6bd8f-88e2-40c9-9b01-2680690ba3ad)
(3) 审查在线书籍:提交完成后,如果没有格式等问题,编译和预发布会成功,我们需要继续做一些审查。
编译成功时,在Pull Request的页面会显示绿色的勾:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOnAkKDNFV5SCTmgwh%2Fimage.png?alt=media&token=dac37f93-2bff-414a-b3c4-724a2a154135)
这时,我们可以打开预发布的书籍链接(不是正式发布的地址): https://steem-guides.github.io/steemh-staging
并查看最新编辑的书籍内容是否可以看到了,以及pdf/epub等格式是否可以提供下载了:
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOom7zVCKqLWAQYEbb%2Fimage.png?alt=media&token=be931240-26d5-4d38-ab0d-3530ca27ff70)
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOp59iHihFOAZCqtuY%2Fimage.png?alt=media&token=483cf1ae-2354-4075-a60b-7bb597d816fe)
由此我们可以看到,我们在上面添加的内容已经成功部署了,但存在几个问题:
-
2.14.1小节的内容不应该从属于2.14。实际上,它也不应该是第2章的内容,我们应该把它放到正确的章节。并且,如果是放在第2章,它也应该和2.14小节处于同一层级;我们应该选择正确的heading(标题),应该是##(第二级)而不是###(第三级)
-
图片的下方显示了图片的文本,但没有意义,我们应该在编辑RMarkdown时输入合适的图片说明,或者不提供说明。即![1.png](02-github-01.png) 中,1.png应该换成更有意义的文字,或者删除。
如果要继续修改,我们可以返回上一步的过程继续修改。如果基本满意,那么编辑的工作就到此大功告成了,恭喜!:)
#4 发布
最后一步,将最新的改动发布到《Steem指南》的在线版本:https://steem-guides.github.io/steemh/
编辑在工作完成后,通知GitHub项目的维护者(Maintainer)已经提交了Pull Request并预发布成功。维护者检查编译和预发布没有问题后,将点击Merge pull request按钮,将当前的Pull Request的代码合并到master branch(主分支)。
![](https://steemitimages.com/640x0/https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LXMinqg0EHzgN2ivoTT%2F-LbOgSPRvJbNm72UV6zT%2F-LbOr2kL4PjdezSw-tQi%2Fimage.png?alt=media&token=13ad79bc-f43d-4b1e-841b-cecff148d172)
合并完成后,对于最新版本书籍的编译和发布将自动触发,将书籍发布到https://steem-guides.github.io/steemh/,并提供pdf和epub的下载。
恭喜所有参与者,至此创作、编辑和合并的工作已经完成了!
不知道你学会了没有?可以根据上面的步骤实验一下哦。
最后
本文适用于《Steem指南》的编辑阅读,也方便其他读者了解《Steem指南》的编写工作是如何完成的。
技术性说明:这里我们没有采用常见的fork模式进行代码贡献,所以需要编辑拥有对于https://github.com/steem-guides/steemh 代码仓库的写权限(加入editors团队)。由于editors没有对于master branch的写权限,必须通过pull request来提交编辑后的成果。
对《Steem指南》编辑的工作流程,如果有更多疑问,请咨询@steem-guides或者@robertyan。
Posted from my blog with SteemPress : http://cnstm.org/team-cn/2019/04/09/%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/
Congratulations @steem-guides! You have completed the following achievement on the Steem blockchain and have been rewarded with new badge(s) :
You can view your badges on your Steem Board and compare to others on the Steem Ranking
If you no longer want to receive notifications, reply to this comment with the word
STOP
Do not miss the last post from @steemitboard:
Vote for @Steemitboard as a witness to get one more award and increased upvotes!
我认领关于RC的那一章,就是最近真的很忙,可能会拖稿(不要打我不要打我不要打我…)
https://busy.org/@ericet/steemkeychain-7n2z3fu72e steem keychain 那章写完