mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-01-13 22:30:37 +08:00
TSL
This commit is contained in:
Xingyu Wang
parent
58fd261dce
commit
b9c8ce5df3
@ -1,191 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (wxy)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write about open source software)
|
||||
[#]: via: (https://opensource.com/article/20/5/write-about-open-source-software)
|
||||
[#]: author: (Dawn Parzych https://opensource.com/users/dawnparzych)
|
||||
|
||||
How to write about open source software
|
||||
======
|
||||
Become a better writer by following these tips.
|
||||
![Typewriter in the grass][1]
|
||||
|
||||
One way to get started with an open source community is to write about it. You can contribute to technical documentation, share how you use the software, or write an article for Opensource.com. But getting started writing is easier said than done. The two most common excuses I hear for not writing are: "I have nothing new to say" and "I'm not a good writer." I'm here to dispel both of those myths.
|
||||
|
||||
### What should you write about?
|
||||
|
||||
> "Hunt for the stories that often get left out."
|
||||
> —Erik Larson
|
||||
|
||||
For some people, the biggest hurdle to writing is generating an idea or topic to write about. It's common to fall into the trap of thinking, "This topic has been written about, so why bother."
|
||||
|
||||
I'm not the first person to write an article on writing, and I won't be the last. What I bring is my unique perspective and things I've learned over the years. I've had people ask me for tips on getting started or how to get better at writing. I decided to turn those suggestions into an article.
|
||||
|
||||
Your writing is a reflection of you. Nobody will tell the story the way you do. Your experiences and perspective may be just what somebody else needs.
|
||||
|
||||
Here are some prompts to help you come up with a topic:
|
||||
|
||||
* What is something you've recently learned? Write about how you learned, what you learned, or what surprised you.
|
||||
* What questions are you frequently asked? Write up the answer.
|
||||
* Did you recently search for a how-to article and weren't satisfied with any of the top search results? Write the article you were looking for.
|
||||
* Did you attend a conference or workshop? Write a post-event summary of what you learned.
|
||||
* Did you start using a new tool? Write up a how-to or getting-started guide.
|
||||
|
||||
|
||||
|
||||
### What type of article are you writing?
|
||||
|
||||
There are different types of writing, including:
|
||||
|
||||
* Technical documentation
|
||||
* How-to guide
|
||||
* Blog
|
||||
* White paper or eBook
|
||||
* Retrospective
|
||||
|
||||
|
||||
|
||||
The type of content will influence your writing style and tone of voice. A blog is more informal and conversational. Technical documentation is more formal and instructional.
|
||||
|
||||
### Who are you writing for?
|
||||
|
||||
Each piece of writing should have a single audience. The audience is the type of person you are writing for. Before you begin writing, it helps to jot down a few characteristics of your reader. It's important to consider who you are writing for, as well as who you _aren't_ writing for—identifying your target audience will shape what to include and what not to include.
|
||||
|
||||
For example, this is who I envisioned when writing this article:
|
||||
|
||||
* Has basic knowledge of writing and grammar
|
||||
* Is interested in improving writing skills
|
||||
* Works in technology as a developer, sales engineer, customer success manager, or similar role
|
||||
* Is not an experienced or advanced writer, may have a couple of published articles on a personal or work blog, and wants to write more
|
||||
* Is writing non-fiction
|
||||
|
||||
|
||||
|
||||
If you have content for multiple audiences, consider breaking it down into different pieces for the different audiences. Some areas to consider in your audience:
|
||||
|
||||
* Level of expertise: novice, intermediate, advanced
|
||||
* Role: manager, individual contributor
|
||||
* Goals: why are they reading?
|
||||
|
||||
|
||||
|
||||
### Words matter
|
||||
|
||||
The words you choose will have an impact on the reader. Difficult words can make an article harder to understand. Unfamiliar words can make the reader feel stupid. Certain words can accidentally offend a reader. Your goal as a writer is to avoid all of these. Here's how.
|
||||
|
||||
#### Use everyday language
|
||||
|
||||
Don't write as a way to show off your vocabulary or the words you've learned from your "Word of the Day" calendar. Write so a reader can understand. There is a reading level associated with every piece of writing. If you're writing technical documentation, aim for about an eighth-grade reading level. This doesn't imply your audience has only an eighth-grade education. It means your writing will be more easily understood. Do you want people to get hung up on the language, or do you want them to walk away feeling like they learned something? Just because you can use big, complicated words doesn't mean you should. Using simple language does not necessarily mean your article will be boring.
|
||||
|
||||
Use tools like [Hemingway App][2] to check the readability of your writing (it's not open source, but it's excellent). For example, after the first draft, this article was assessed at a fifth-grade reading level. Hemingway also provides suggestions on how to improve your writing—identifying hard-to-read sentences or places to alter word choice.
|
||||
|
||||
If you're struggling with coming up with alternative words, check out the suggestions at the [Plain English Campaign][3] or the crowdsourced suggestions at [Power Thesaurus][4].
|
||||
|
||||
#### Know which words to avoid
|
||||
|
||||
> "Substitute 'damn' every time you're inclined to write 'very'; your editor will delete it and the writing will be just as it should be."
|
||||
> —Mark Twain
|
||||
|
||||
When writing a tutorial or how-to guide, here are some words to avoid, including "simple," "easy," and "just." You, an expert on the topic you're writing about, may find things easy after years of practice. A beginner may not find things simple or easy. Your readers may get frustrated because they don't find the process or explanation simple.
|
||||
|
||||
Have you ever had to reread a sentence or paragraph multiple times because you couldn't figure out what the writer was saying? Have you ever given up on an article because it wasn't making sense to you? I have.
|
||||
|
||||
As a writer, do you want your readers to feel confused or unintelligent? I hope not.
|
||||
|
||||
Other words to avoid in your writing:
|
||||
|
||||
* That
|
||||
* Really
|
||||
* Very
|
||||
* So
|
||||
* In order to
|
||||
|
||||
|
||||
|
||||
Generally, these words can be deleted without changing the meaning of a sentence.
|
||||
|
||||
After I finish writing, I search a document for instances of those words. When I searched through this document, I found the following sentence:
|
||||
|
||||
> "This doesn't imply that your audience only has an eighth-grade education, it means that your writing will be more easily understood."
|
||||
|
||||
Two instances of "that" appear in this sentence. They're not adding value to the sentence. They can be deleted without changing its meaning. Removing those instances shortens the sentence, and shorter sentences are easier to understand. And speaking of shorter sentences, I also re-wrote it as two sentences.
|
||||
|
||||
> "This doesn't imply your audience has only an eighth-grade education. It means your writing will be more easily understood."
|
||||
|
||||
#### Use inclusive language
|
||||
|
||||
The historical context of words and phrases can lead to people feeling excluded or offended. When writing, you want to make the reader feel included. When you use inclusive language, it makes your reader feel understood, respected, and like they belong. I refer to this [guide on using inclusive language][5] from Buffer.
|
||||
|
||||
### Revising and editing
|
||||
|
||||
> "Almost all good writing begins with terrible first efforts. You need to start somewhere."
|
||||
> —Anne Lamott
|
||||
|
||||
Writing is an iterative process. If you think writers sit down at their desk and, within an hour, have a completed article ready to be published, think again. Some articles take me weeks to complete. Here's a standard process for me:
|
||||
|
||||
* Write a rough first draft. By rough, I mean _rough_. I write without worrying about grammar. The idea is to get words out of my head and onto paper. This step can take anywhere from an hour to a couple of weeks.
|
||||
* Put the draft away for some time. This can be anywhere from a couple of hours to a couple of days, depending on the publishing timeline.
|
||||
* Review the draft. Make tweaks and edits.
|
||||
* Ask for feedback, either from a coworker or a friend. During this phase of feedback, I focus on clarity. Does everything make sense? Is anything confusing, any missing sections?
|
||||
* Incorporate feedback. No matter how experienced you are at writing, other writers reviewing your work will make it better.
|
||||
|
||||
|
||||
|
||||
At this stage, I have a pretty solid draft. Now comes my least favorite part of writing—editing. The Hemingway App I mentioned earlier not only tells you the reading level but also provides suggestions to improve your writing. I also use Grammarly to help with grammar edits. For open source alternatives to Grammarly, check out [Language Tool][6] or this article on [open source writing tools][7].
|
||||
|
||||
One of my writing challenges is using commas appropriately. Grammarly helps me figure out where I miss or misuse a comma. Grammarly identified 43 issues related to the correctness of this article's final draft. The majority were comma errors.
|
||||
|
||||
![Errors identified by Grammarly][8]
|
||||
|
||||
(Dawn Parzych, [CC BY-SA 4.0][9])
|
||||
|
||||
In addition to grammatical errors, the app also provides suggestions to help with clarity, engagement, and delivery (some of these features may not be available in the free version). This includes things like word choice and using active vs. passive voice. Some suggestions I accept; others I reject. After reviewing all the alerts and suggestions, Grammarly reports back across all dimensions.
|
||||
|
||||
![Grammarly results][10]
|
||||
|
||||
(Dawn Parzych, [CC BY-SA 4.0][9])
|
||||
|
||||
Don't be afraid to ask for help with your writing. Behind every good writer is a good editor or a good editing app.
|
||||
|
||||
### Style guides
|
||||
|
||||
Style guides provide standards for improving communication in writing. They include aspects such as punctuation, grammar, and word usage. If writing a document for your company, check to see if it uses a style guide. If it doesn't have a style guide, or if you're writing for yourself, here are some common style guides to follow:
|
||||
|
||||
* [Chicago Manual of Style][11]
|
||||
* [Google Developer Documentation Guide][12]
|
||||
* [Microsoft Writing Style Guide][13]
|
||||
* [AP Stylebook][14]
|
||||
|
||||
|
||||
|
||||
Writing is a way to share your thoughts and knowledge with the community. The only way to get started writing is to start typing. Use these suggestions to fine-tune your writing.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/5/write-about-open-source-software
|
||||
|
||||
作者：[Dawn Parzych][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/dawnparzych
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/doc-dish-lead.png?itok=h3fCkVmU (Typewriter in the grass)
|
||||
[2]: http://www.hemingwayapp.com/
|
||||
[3]: http://www.plainenglish.co.uk/the-a-z-of-alternative-words.html
|
||||
[4]: https://www.powerthesaurus.org/
|
||||
[5]: https://open.buffer.com/inclusive-language-tech/
|
||||
[6]: https://languagetool.org/
|
||||
[7]: https://opensource.com/article/20/3/open-source-writing-tools
|
||||
[8]: https://opensource.com/sites/default/files/uploads/grammarlyerrors.png (Errors identified by Grammarly)
|
||||
[9]: https://creativecommons.org/licenses/by-sa/4.0/
|
||||
[10]: https://opensource.com/sites/default/files/uploads/grammarlyresults.png (Grammarly results)
|
||||
[11]: https://www.chicagomanualofstyle.org/home.html
|
||||
[12]: https://developers.google.com/style
|
||||
[13]: https://docs.microsoft.com/en-us/style-guide/welcome/
|
||||
[14]: https://www.apstylebook.com/
|
||||
@ -0,0 +1,175 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (wxy)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write about open source software)
|
||||
[#]: via: (https://opensource.com/article/20/5/write-about-open-source-software)
|
||||
[#]: author: (Dawn Parzych https://opensource.com/users/dawnparzych)
|
||||
|
||||
如何写好关于开源软件的文章
|
||||
======
|
||||
|
||||
> 通过以下提示，成为一个更好的作家。
|
||||
|
||||
![Typewriter in the grass][1]
|
||||
|
||||
开始接触开源社区的一个方法就是写关于它的文章。你可以贡献技术文档，分享你如何使用软件，或者为我们写一篇文章。但是开始写作是说起来容易做起来难。我听到的最常见的两个不写文章的借口是：“我没有什么新东西可说”和“我不是一个好的作家”。我在这里是为了打破这两个误区。
|
||||
|
||||
### 你应该写什么？
|
||||
|
||||
> “寻找那些经常被遗漏的故事。”
|
||||
> 埃里克·拉尔森
|
||||
|
||||
对于一些人来说，写作的最大障碍是产生一个想法或话题，以写出一个想法或话题。很容易就落入了这样的陷阱：“这个话题已经写过了，何必再麻烦。”
|
||||
|
||||
我不是第一个写文章的人，也不会是最后一个。我带来的是我独特的视角和这些年来所学到的东西。曾经有人向我请教过一些关于写作入门的建议，或者是如何让自己的写作更上一层楼。我决定把这些建议变成一篇文章。
|
||||
|
||||
文如其人，没有人会以你的方式来述事，你的经历和视角可能正是别人所需要的。
|
||||
|
||||
这里有一些提示，可以帮助你想出一个主题：
|
||||
|
||||
* 你最近学到了什么东西？写出你是如何学习的，你学到了什么，或者是什么事情让你感到惊讶。
|
||||
* 你经常被问到的问题是什么？把答案写出来。
|
||||
* 你最近是否在搜索一篇怎么做的文章，但在搜索结果中，你对排名靠前的文章不满意？请写出你要找的文章。
|
||||
* 你是否参加过一次会议或研讨会？写一篇会后总结，说明你所学到的东西。
|
||||
* 你开始使用新工具了吗？写一份操作指南或入门指南。
|
||||
|
||||
### 你写的是什么类型的文章？
|
||||
|
||||
有不同类型的文章，包括:
|
||||
|
||||
* 技术文档
|
||||
* 操作指南
|
||||
* 博客
|
||||
* 白皮书或电子书
|
||||
* 回顾性的文章
|
||||
|
||||
内容的类型会影响你的写作风格和语气。博客更多的是非正式和对话式的。技术文档更正式，更具有指导性。
|
||||
|
||||
### 你是为谁而写的？
|
||||
|
||||
每一篇文章都应该有一个受众。受众是指你所写的对象是什么类型的人。在你开始写作之前，写下你的读者的一些特征，这对你的读者有帮助。重要的是要考虑到你要为谁写，以及你**不是为**谁写的 —— 确定你的目标受众将决定你的目标受众，要包括哪些内容和不包括哪些内容。
|
||||
|
||||
例如，我在写这篇文章的时候，我设想的目标受众是这样的。
|
||||
|
||||
* 有基本的写作和语法知识
|
||||
* 有兴趣提高写作能力
|
||||
* 在技术领域担任开发人员、销售工程师、客户经理或类似职位的工作
|
||||
* 不是有经验或高级作家，可能在个人或工作博客上发表过几篇文章，想写更多的文章。
|
||||
* 非虚构写作
|
||||
|
||||
如果你有针对多个受众的内容，可以考虑针对不同的受众将其分解成不同的内容。在你的受众中需要考虑的一些部分。
|
||||
|
||||
* 专业水平：新手、中级、高级
|
||||
* 作用：管理人员、个人贡献者
|
||||
* 目标：他们为什么要阅读这些？
|
||||
|
||||
### 言语很重要
|
||||
|
||||
你选择的词语会对读者产生影响。晦涩难懂的词会使文章更难理解，不常见的词会让读者觉得自己很笨，某些词可能会不小心冒犯读者。作为一个作家，你的目标是避免所有这些。下面是怎么做的。
|
||||
|
||||
#### 使用日常用语
|
||||
|
||||
不要把写作作为炫耀你的词汇量或你从“每日一字”台历上学到的单词的方式。写作是为了让读者能够理解。每一篇文章都有一个关联的阅读水平。如果你写的是技术文档，那么你的目标大约是初中的阅读水平。这并不意味着你的受众只有初中的教育水平。它意味着你的写作会更容易被人理解。你想让人们对这些言语过目不忘，还是想让他们觉得自己学到了什么？虽然你可以使用长而复杂的词汇，但并不意味着你应该这样做。使用简单的语言不一定意味着你的文章会很无聊。
|
||||
|
||||
使用 [Hemingway 应用][2]等工具来检查你的作文的可读性（它不是开源的，但很优秀）。比如说，这篇文章经过初稿后，被评定为五级阅读水平。Hemingway 还提供了如何改进写作的建议 —— 找出难读的句子或需要改变选词的地方。
|
||||
|
||||
如果你正在纠结于想出替代词，可以查看 [Plain English Campaign][3] 的建议或 [Power Thesaurus][4] 的众包建议。
|
||||
|
||||
#### 知道应该规避哪些词
|
||||
|
||||
> “每次你想写‘非常’的时候，就用‘该死的’代替；你的编辑会把它删掉，写出来的东西就会像它应该写的那样。”
|
||||
> 马克·吐温
|
||||
|
||||
在写教程或指南的时候，这里有一些要避免的词，包括“<ruby>简单<rt>simple</rt></ruby>”、“<ruby>容易<rt>easy</rt></ruby>”和“<ruby>就这样<rt>just</rt></ruby>”。你是你所写的主题的专家，经过多年的实践，可能会觉得事情很简单。而初学者可能会觉得事情不简单，也不容易。你的读者可能会感到沮丧，因为他们觉得过程或解释并不简单。
|
||||
|
||||
你是否曾经因为无法理解作者的意思而不得不多次重读一个句子或段落？你有没有因为一篇文章对你来说没有意义而放弃过？我有过。
|
||||
|
||||
作为一个作家，你希望你的读者感到困惑或不理解吗？我希望不会。
|
||||
|
||||
在你的写作中要避免的其他词语
|
||||
|
||||
* <ruby>这件事<rt>That</rt></ruby>
|
||||
* <ruby>真的<rt>Really</rt></ruby>
|
||||
* <ruby>非常<rt>Very</rt></ruby>
|
||||
* <ruby>所以<rt>So</rt></ruby>
|
||||
* <ruby>为了<rt>In order to</rt></ruby>
|
||||
|
||||
一般来说，这些词可以在不改变句子意思的情况下删除。
|
||||
|
||||
在我写完之后，我会在一个文档中搜索这些词的实例。当我在这个文档中搜索时，我发现了以下这句话。
|
||||
|
||||
> “这并不意味着你的受众只有初中的教育水平*这件事*，而意味着你的写作会更容易被理解*这件事*。”
|
||||
|
||||
这句话中出现了两个“<ruby>这件事<rt>That</rt></ruby>”的例子。它们并没有给句子增加价值。它们可以被删除而不改变其意义。删除这些实例可以缩短句子，而更短的句子更容易理解。而说到短句，我还把它改写成了两句话。
|
||||
|
||||
> “这并不意味着你的受众只有初中的教育水平。它意味着你的写作会更容易被人理解。”
|
||||
|
||||
#### 使用包容性语言
|
||||
|
||||
词语和短语的历史背景会让人感到被排斥或反感。在写作时，你要让读者感到被包容。当你使用包容性的语言时，会让读者感到被理解、被尊重，感觉自己是属于他们的。我参考了 Buffer 中的这篇[关于使用包容性语言的指南][5]。
|
||||
|
||||
### 修订和编辑
|
||||
|
||||
> “几乎所有好的写作都是从可怕的第一次努力开始的。你需要从某个地方开始。”
|
||||
> 安妮·拉莫特
|
||||
|
||||
写作是一个迭代的过程。如果你认为作家们坐在办公桌前，在一个小时内就能完成一篇文章发表，那么请你再想一想。有些文章需要我花几个星期的时间来完成。以下是我的一个标准流程：
|
||||
|
||||
* 写一个粗略的初稿。我说的粗略，我的意思是*草稿*。我写的时候不用担心语法问题。我的想法是让文字从我的脑海中浮现出来，写在纸上。这一步可能需要一个小时到几周的时间。
|
||||
* 将草稿放一段时间。这可能需要几个小时到几天的时间，这取决于出版时间线。
|
||||
* 审阅草稿。进行调整和编辑。
|
||||
* 征求反馈意见，可以是同事或朋友的反馈意见。在这个阶段的反馈中，我的重点是明确性。是否有意义？是否有什么令人困惑的地方，有什么缺失的部分？
|
||||
* 纳入反馈意见。无论你的写作经验有多丰富，其他作者审阅你的作品，都会让你的作品变得更好。
|
||||
|
||||
在这个阶段，我有了一个相当扎实的草稿。现在到了我最不喜欢的写作部分 —— 编辑。我之前提到的 Hemingway 应用不仅能告诉你阅读水平，还能提供改进写作的建议。我还使用 Grammarly 来帮助编辑语法。关于 Grammarly 的开源替代工具，请查看[语言工具][6]或这篇文章中的[开源写作工具][7]。
|
||||
|
||||
我的写作挑战之一就是适当地使用逗号。Grammarly 可以帮助我找出我错过或误用逗号的地方。Grammarly 发现了 43 个与这篇文章的最终草稿的正确性有关的问题。其中大部分是逗号错误。
|
||||
|
||||
![Errors identified by Grammarly][8]
|
||||
|
||||
除了语法错误之外，该应用程序还提供了一些建议，以帮助提高清晰度、参与度和表达能力（其中一些功能可能在免费版中没有）。这包括单词选择和使用主动语气与被动语气等。有些建议我接受，有些则拒绝。在审查了所有的警报和建议后，Grammarly 会在所有的维度上进行反馈。
|
||||
|
||||
![Grammarly results][10]
|
||||
|
||||
不要害怕寻求写作上的帮助。每一个好的作家背后都有一个好的编辑或好的编辑应用。
|
||||
|
||||
### 风格指南
|
||||
|
||||
文体指南为改进写作中的交流提供了标准。它们包括标点符号、语法和用词等方面。如果是为你的公司撰写文档，请检查一下是否使用了文体指南。如果没有文体指南，或者你是为自己写的，下面是一些常用的文体指南。
|
||||
|
||||
* [芝加哥文体手册][11]
|
||||
* [谷歌开发者文档指南][12]
|
||||
* [微软写作风格指南][13]
|
||||
* [AP 风格手册] [14]
|
||||
|
||||
写作是一种与社会分享自己的思想和知识的方式。开始写作的唯一方法就是开始打字。用这些建议来微调你的写作。
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/5/write-about-open-source-software
|
||||
|
||||
作者：[Dawn Parzych][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[wxy](https://github.com/wxy)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/dawnparzych
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/doc-dish-lead.png?itok=h3fCkVmU (Typewriter in the grass)
|
||||
[2]: http://www.hemingwayapp.com/
|
||||
[3]: http://www.plainenglish.co.uk/the-a-z-of-alternative-words.html
|
||||
[4]: https://www.powerthesaurus.org/
|
||||
[5]: https://open.buffer.com/inclusive-language-tech/
|
||||
[6]: https://languagetool.org/
|
||||
[7]: https://opensource.com/article/20/3/open-source-writing-tools
|
||||
[8]: https://opensource.com/sites/default/files/uploads/grammarlyerrors.png (Errors identified by Grammarly)
|
||||
[9]: https://creativecommons.org/licenses/by-sa/4.0/
|
||||
[10]: https://opensource.com/sites/default/files/uploads/grammarlyresults.png (Grammarly results)
|
||||
[11]: https://www.chicagomanualofstyle.org/home.html
|
||||
[12]: https://developers.google.com/style
|
||||
[13]: https://docs.microsoft.com/en-us/style-guide/welcome/
|
||||
[14]: https://www.apstylebook.com/
|
||||
Loading…
Reference in New Issue
Block a user