编写 Code Project 文章指南

Marc Clifton

4.87/5 (220投票s)

2002年12月14日

CPOL

22分钟阅读

977022

一些关于撰写一篇高质量文章的技巧。

为什么要写文章？

写一篇高质量文章的动机是一个重要因素。本节讨论了可能的动机。

知名度

Code Project 在编程界拥有很高的知名度。它拥有不断增长的会员和文章基础，论坛流量巨大，Code Project 的“常客”们经常光顾帮助论坛。使用任何主流搜索引擎对许多编程术语进行关键词搜索时，Code Project 的命中率都很高。如果你写的文章解决了一个问题或演示了如何使用某项特定技术，那么当人们搜索解决方案/示例时，你的文章很可能会出现。这也是找到工作的好方法——就我个人而言，我已经通过在 Code Project 上的知名度获得了好几个为期多年的合同。

提交文章时，请仔细考虑你的显示名称。当然，你可以隐藏在别名之后，但如果你想让你的文章（以及可能的文章奖项！）引起关注，那么你可能要考虑使用你的真实姓名或姓名缩写，这样潜在的雇主就能确信你引用的文章和奖项确实是你自己撰写/赢得的。很可能，你写文章的动机与你的简历无关，但请记住，在某个时候你可能会意识到这是一个附带的好处。要更改文章上显示的作者姓名，只需登录 Code Project，点击“我的设置”（My Settings），然后输入你的名字。你的文章将会自动更新。

同行评审

我喜欢写文章的原因之一是同行评审。有很多聪明人混迹于 Code Project，多年来我发现大家的评论非常有帮助——他们指出我犯错的地方、可以做得更好的地方，或者只是指出一种不同的方法。很难在其他任何地方找到这样一个世界级的社区——作为一名顾问，我通常因为被认为是专家而被聘用，能接触到一个我認為其中许多成员的专业技能远超于我的社区，感觉非常好。

为社区做贡献

这是一个非常简单的概念，但也是我从其他成员那里听到的——他们从 Code Project 获得了大量有用的信息，并有动力自己写点东西回馈社区。美好而简单！

无论原因为何……

我猜你希望你的文章被别人阅读。这意味着，和其他任何事情一样，你需要迅速让读者相信这篇文章是专业的，并且你在某种程度上分享了关于某个主题的专业知识。读者群可能有数百万之众（如今我看到 Code Project 的文章被到处引用），人们无法预测某人为什么会点开你的文章——也许这个主题是他们需要学习的，也许他们正在寻找一个提供用法示例的代码片段，也许他们只是在浏览自己不熟悉的主题。无论如何，你的文章是*可见的*，写一篇好文章只会对你最有利。

怎样才算一篇不错的文章？

以下是创作一篇不错文章的一些要点——希望它能经受住未知读者的评判。

深思熟虑——用简洁且深思熟虑的计划来呈现你的想法。我通常会先写一个大纲，然后充实细节，修改大纲，最后再填写正文。
视觉吸引力——大量点缀截图、流程图、UML图等，能为读者提供一个很好的视觉“调剂”。使用图片来：
- 展示中间过程以及最终结果
- 如果适用，用来阐述你的架构
- 阐述复杂的概念，如流程、模式、状态、消息传递、互联互通等等。一图胜千言！
拼写、语法和可读性
- 在今天这个时代，不对你的文章进行拼写检查是完全没有借口的，尤其是有那么多免费的编辑器和拼写检查器。讽刺的是，即使我用了拼写检查器，拼写错误似乎总会溜进来，尤其是像“for”和“four”之类的词。这些错误很难被发现！
- 语法可能更难，特别是如果你不是英语母语者。可以考虑请另一位受人尊敬的成员帮你审阅文章。

使用文章模板的内容建议

当你使用文章提交向导时，系统会提供一个样板章节列表供你填写。

就我个人而言，我总是在使用文章提交向导之前先写好文章，但如果这是你第一次写，如果模板中的标题合适并且你需要帮助构思内容，那么就使用它们吧。

关于“简短描述”——一篇好文章可以简短而精炼（尽管那样你可能会被批评说它更像一篇博客文章），也可以是鸿篇巨制，你需要详细描述几种技术来描绘完整的画面，或者介于两者之间。如果你打算写一篇鸿篇巨制，我建议你考虑使用目录生成器来帮助读者导航和选择阅读的主题——请参阅本文末尾的“工具”部分。

请求导师帮助

如这里所解释的，如果你想在润色文章方面获得帮助，可以请求一位导师审阅你的文章。

格式化图形

图形应该只展示必要的信息量——裁剪你的图片，使其只包含与补充文本相关的内容——我们不需要看到你的任务栏、桌面背景等。如果你的图片非常大，可以考虑使用一个较小的缩略图或图片的一小部分，并附上一个像“点击查看全尺寸图片”这样的文本链接，让读者可以点击以100%的缩放级别查看完整的图片。

思路流程

一篇文章应该有某种大纲，通常通过标题来体现。标题能让读者快速了解你的思考过程和文章的流程。如果你的文章长度超过几屏滚动，可以考虑创建一个目录（请参阅下面的“工具”部分）。

专注

我倾向于写的文章主题，其内容可能足够写一整本书。如果你面临这种情况，可以考虑先写一个大纲，像激光束一样聚焦于你想写的具体概念。坚持计划！

多部分文章

帮助读者消化文章的另一种方法是将其分成几篇文章（这也会增加你的文章数量，哈哈哈）。如果你考虑写一个多部分系列文章，请记住，系列中的每一篇后续文章都应该：

建立在前一篇文章工作的基础上
代表一个完整的概念——无论你的文章谈论什么，都应该在当前文章中是一个完整的包。

上面第二点的目的是为了防止人们仅仅为了写多部分文章而写——每一部分的概念之间应该有清晰的划分。

格式化文本

格式化的另一个方面是需要对HTML有基本的了解。这里有一个非常简短的指南：

<p> - 段落分隔符
<br> - 强制换行
< - ‘<’ 字符
> - ‘>’ 字符
& - ‘&’ 字符
<h2> - 主标题的开始
</h2> - 主标题的结束
<h3> - 副标题的开始
</h3> - 副标题的结束

当然还有许多其他有用的HTML命令，但我认为这些是必不可少的。

代码格式化

代码格式化的一个准则是，在800x600分辨率的显示器上，代码应该无需水平滚动即可阅读。有一个很棒的工具可以用来查看你的文章及其代码在800x600显示器上的样子（请参阅下面的“工具”部分）。

代码格式化的另一个方面是决定要呈现哪些代码，以及在一个<pre>块中呈现多少代码。几条简单的规则就足够了：

只呈现与你的观点核心相关的代码。
如果一个代码块超过一个屏幕的长度，可以考虑将代码分成几个部分，在每个部分中讨论其要点。

颜色和格式

一篇文章的目标是易于阅读。过多的颜色、下划线、粗体标签、大写字母等会降低可读性。你还需要确保与其他文章保持一定程度的一致性，所以强烈建议你不要偏离 Code Project 的风格太远——例如，不要发明你自己的主/副标题配色方案。

一些进一步的想法

以下是额外的内容创意，部分来自于戴尔·卡耐基的《如何赢得朋友和影响他人》以及如何进行2分钟演讲。请记住，这些只是建议——许多文章不需要遵循这个大纲。

你的主题是什么？

这应该描述你正在写的内容。它通常放在引言中，提供一个简短的大纲（由你的文章标题支持）来描述文章内容通常很有帮助。如果该主题有一些你建议读者具备的特定背景知识，那么一个简要的概述对你的读者会很有价值。

你为什么是专家？

简要描述导致你写这篇文章的经历。你试图解决什么问题？如果适用，你可能还想简要描述一下你与编程无关但促使你写这篇文章的知识。例如，如果你正在写一篇解决某个电气工程问题的文章，请描述一下你在这个领域的经验。

许多作者写文章是因为他们希望分享自己刚刚学到的东西。这很棒，也是 Code Project 的精神所在。如果这是你第一次写文章，要认识到，虽然你可能是你所写内容的专家，但你的写作技巧可能还没有打磨好。务必检查你的作品，一旦文章发布，就要准备好接受建议和改进。你的文章会因此变得更好，而且没有比这更好的学习方式了。当然，当我回顾我早期的作品时，我常常对我现在认为的低质量写作感到汗颜。我相信10年后，当我看到今天写的文章时，我也会做同样的事情！

你学到了什么？

描述你在解决文章所解决的任何问题的过程中学到了什么。有时这可能与你最初的主题大相径庭，但与文章内容本身同样有价值。

读者能学到什么？

这不一定只是对你的主题的重复描述。你可以在这里更详细地说明你使用了哪些技术、工具和其他特殊解决方案。许多文章中都蕴含着知识的瑰宝。如果我看到一篇关于在 Visio 中绘制数据库模型的文章，我可能根本不关心数据库，但我可能对你的 Visio 接口感兴趣，而另一个人可能不关心 Visio，但想看看你是如何提取数据库模式的。

所以，“我能学到什么”这一部分实际上是要求你思考你的文章所展示的其他有趣的事情。

修订历史

许多作者会不时更新他们的文章，修复错误、添加功能、更新文章内容本身。可以考虑加入一个关于你的修订历史的部分。Code Project 有一个很棒的修订历史功能（可以通过点击左侧边栏上的“Revisions”链接查看）。例如：

然而，有一个带注释的修订说明会非常有帮助。顺便问一下，你能发现作者文章标题中的拼写错误吗？

结论

这是你真正可以自由发挥的机会。你还有哪些无法归入其他地方的补充信息？你是否会继续研究你的主题？也许可以透露一下你接下来打算写些什么。你对什么样的反馈感兴趣？你编写代码的经历是怎样的？

一些额外的建议

关键词

成员“.S.Rod.”建议：

无论一篇文章写得好不好，我更关心的是，通过在搜索引擎中输入一个简单的关键词（有时可能是两个），能多容易地找到文章中有用的源代码。

这提出了一个重要观点——要好好选择你的标签，这样当有人在 Code Project 上搜索你所写主题的信息时，你的文章就更有可能出现在列表中。当你使用提交向导时，有大量的标签可供选择。

做好功课

成员 Rohit Sinha 写道：

检查一下这个主题是否已经被涵盖。如果已经有了，你的文章比其他的文章多了些什么？它是否用不同的方式处理问题？它是否提供了另一种解决方案？最好也提及其他的文章，并解释为什么你认为你的文章是必要的。在文章标题旁边的文章描述中也应该提供一个提示。毕竟，如果有10篇关于悬停按钮的文章，我应该读哪一篇？

这是极好的建议。

提交文章供 Code Project 发布

如果你对通过提交向导（下面将讨论）提交文章感到不自在，你可以简单地从主“提交新文章”（Submit a new Article）屏幕将你的文章（以 zip 形式）发送给 Code Project。

使用提交向导

提交向导是一个出色的编辑器，你可以用它来立即发布你的文章，可以说是把它“扔给狼群”。

选择一个板块和子板块

这是一个庞大的板块列表，大致分为以下几类：

桌面开发
Web 开发
移动开发
云计算
企业系统
数据库
多媒体
语言
平台、框架和库
通用编程
图形/设计
开发生命周期
一般阅读
第三方产品
导师资源

这个列表可能会让人望而生畏，而且子板块本身也可能有很多项。也可能会令人困惑，因为你的文章可能涵盖了好几个合理的板块，比如“多媒体”、“移动开发”和“数据库”。我的建议是，考虑一下你的文章最适合哪个板块，并仔细阅读子板块，看看是否能进一步细化。如果不确定，就在“给编辑的评论”（Comments for the editor）框里给编辑留个言。

它就在文章所见即所得（WYSIWYG）编辑器的正下方。

文章标题

选择板块和子板块后，输入你的文章标题。这应该是你文章的*标题*，不同于一句话描述。有时先写一个一句话的描述，然后再从中确定标题会更容易些。如果对你有帮助，可以把一句话描述看作是对你标题的进一步详细说明。例如：

我用我文章的主标题来构思这一句话描述。

一句话描述

这一句话描述会出现在 Code Project 文章列表的首页，所以简洁地吸引读者点击你的文章非常重要——你可以把标题看作是鱼钩，而一句话描述则是鱼线和铅坠。如果你不熟悉这个习语，请阅读这里（维基百科是不是很神奇？）。

文章本身

提交向导提供了一个很棒的内联编辑器。

话虽如此，在提交向导中写文章仍然是件麻烦事，这并非 Code Project 的错，而是因为用在线格式写一篇中等或较长的文章本身就不是最好的方式。不过，提交向导已经有了极大的改进，因为你可以保存草稿：

通过点击绿色的“保存草稿”（Save Draft）按钮，然后你可以稍后回到“提交文章”（Submit an Article）菜单继续编辑你的文章。

然后从你当前正在编辑的任何一篇文章中选择。

自动保存功能也很棒，尤其是在飓风导致你的网络连接中断时。

建议流程

我是这样做的：

我首先在一个HTML编辑器中写文章（从Word之类的软件转换过来也很麻烦，所以我不推荐）。我做的唯一格式化是标题（从二级标题开始）和用于代码块的 <pre> 标签。有时我会用 <code> 标签来标记文本内的代码元素，但我通常把这个留到收尾阶段再做。
然后我点击所见即所得（WYSIWYG）编辑器窗口工具栏中的“HTML”按钮，这会带我进入HTML视图。
然后我将我的HTML粘贴到窗口中。
然后我再次点击“HTML”按钮返回所见即所得模式，这样我就可以看到它的样子了。

清理

所见即所得（WYSIWYG）编辑器不做拼写检查（尽管你的浏览器可能会添加这个功能），这就是为什么我更喜欢使用带拼写检查的编辑器。如果你正在使用所见即所得编辑器，我建议你将文章复制到一个有拼写检查功能的编辑器中，修复所有拼写错误，然后再粘贴回来。
我还会通读文章，高亮所有行内代码，然后点击工具栏中的“var”按钮，这样文本内的代码词就会使用正确的样式。
我还会检查代码块的宽度，并强制硬回车以避免滚动。这个问题现在不那么严重了，因为 Code Project 现在使用了时髦的水平和垂直滚动的代码框，如果代码的宽度或高度过长的话。
说到代码块（那些在 <pre> 标签之间的东西），请检查并从工具栏的下拉菜单中选择正确的语言，以便语法高亮能正常工作。