mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-03-12 01:40:10 +08:00
Merge remote-tracking branch 'LCTT/master'
This commit is contained in:
Xingyu Wang
commit
5ea9f5ea6e
@ -1,30 +1,32 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: reviewer: (wxy)
|
||||
[#]: publisher: (wxy)
|
||||
[#]: url: (https://linux.cn/article-12005-1.html)
|
||||
[#]: subject: (6 Raspberry Pi tutorials to try out)
|
||||
[#]: via: (https://opensource.com/article/20/3/raspberry-pi-tutorials)
|
||||
[#]: author: (Lauren Pritchett https://opensource.com/users/lauren-pritchett)
|
||||
|
||||
6 个可以尝试的树莓派教程
|
||||
======
|
||||
这些树莓派项目均旨在简化你的生活并提高生产力。
|
||||
![Cartoon graphic of Raspberry Pi board][1]
|
||||
|
||||
没有什么比体验树莓派创作结果更令人兴奋了。经过数小时的编程、测试和徒手构建，你的项目终于开始成形，你不禁大喊 “woohoo！”。树莓派可以带给日常生活的可能性让我着迷。无论你是想学习新知识、尝试提高效率还是只是乐在其中，本文总有一个树莓派项目适合你。
|
||||
> 这些树莓派项目均旨在简化你的生活并提高生产力。
|
||||
|
||||
|
||||
|
||||
没有什么比体验树莓派创作结果更令人兴奋了。经过数小时的编程、测试和徒手构建，你的项目终于开始成形，你不禁大喊 “哇哦！”树莓派可以带给日常生活的可能性让我着迷。无论你是想学习新知识、尝试提高效率还是只是乐在其中，本文总有一个树莓派项目适合你。
|
||||
|
||||
### 设置 VPN 服务器
|
||||
|
||||
本[教程][[2]教你如何使用树莓派添加网络安全层。这个项目不仅有实际好处，而且还能为你带来很多乐趣。额外的安全性使你可以放心地做其他项目，例如下面列出的项目。
|
||||
本[教程][2]教你如何使用树莓派添加一个网络安全层。这个项目不仅有实际好处，而且还能为你带来很多乐趣。额外的安全性使你可以放心地做其它项目，例如下面列出的项目。
|
||||
|
||||
### 创建一个物体跟踪摄像机
|
||||
|
||||
树莓派之所以具有吸引力，是因为它提供了较低的入门门槛来学习机器学习等新技术。这份[逐步指南][3]提供了详尽的说明，说明了如何构建一个全景摄像头，以便使用 TensorFlow 和树莓派跟踪运动。
|
||||
树莓派之所以具有吸引力，是因为它提供了较低的入门门槛来学习机器学习等新技术。这份[分步指南][3]提供了详尽的说明，说明了如何构建一个全景摄像头，以便使用 TensorFlow 和树莓派跟踪运动。
|
||||
|
||||
### 使用照片幻灯片展示你最喜欢的回忆
|
||||
|
||||
你是否曾经问过自己：“我应该怎么处理这些数码照片？”。如果你像我一样，那么答案是“是”。在朋友和家人圈子中，我被公认为摄像爱好者。这就是为什么我喜欢这个树莓派项目。在[本教程][4]中，你将学习如何设置照片幻灯片，以便轻松地在家里展示自己喜欢的回忆，而无需打印机！
|
||||
你是否曾经问过自己：“我应该怎么处理这些数码照片？”。如果你像我一样这样想过，那么答案是“是”。在朋友和家人圈子中，我被公认为摄像爱好者。这就是为什么我喜欢这个树莓派项目。在[本教程][4]中，你将学习如何设置照片幻灯片，以便轻松地在家里展示自己喜欢的回忆，而无需打印机！
|
||||
|
||||
### 玩复古电子游戏
|
||||
|
||||
@ -32,13 +34,13 @@
|
||||
|
||||
### 为你的娱乐中心搭建时钟
|
||||
|
||||
在过去的十年中，家庭娱乐中心发生了很大的变化。我的家人完全依靠流媒体服务来观看节目和电影。我之所以爱它是因为我可以通过移动设备或语音助手控制电视。但是，当你不再能看眼时钟时，便会失去一定程度的便利！请遵循[这些步骤][6]，使用树莓派从头开始搭建自己的时钟显示。
|
||||
在过去的十年中，家庭娱乐中心发生了很大的变化。我的家人完全依靠流媒体服务来观看节目和电影。我之所以爱它是因为我可以通过移动设备或语音助手控制电视。但是，当你不再能一眼看到时钟时，便会失去一定程度的便利！请遵循[这些步骤][6]，使用树莓派从头开始搭建自己的时钟显示。
|
||||
|
||||
### 扩大自制啤酒的生产规模
|
||||
|
||||
在[本教程][7]中，经验丰富的家庭酿酒师分享了他建立电动啤酒酿造系统的经验。该项目需要在硬件和零件上进行更多的前期投资，但由此产生的效率和一致性让这些值得。为此祝贺！
|
||||
|
||||
如果你是像我这样的树莓派新手，那么我建议你阅读我们可下载的树莓派指南。我们的[单页速查表][8]提供了入门指南。有关更多技巧和教程，我们的[综合指南][9]涵盖了一些主题，例如选择树莓派、保持更新、为社区做出贡献等。
|
||||
如果你是像我这样的树莓派新手，那么我建议你阅读我们这些可下载的树莓派指南。我们的[单页速查表][8]提供了入门指南。有关更多技巧和教程，我们的[综合指南][9]涵盖了一些主题，例如选择树莓派、保持更新、为社区做出贡献等。
|
||||
|
||||
你会尝试哪个树莓派项目？让我们在评论中知道。
|
||||
|
||||
@ -49,7 +51,7 @@ via: https://opensource.com/article/20/3/raspberry-pi-tutorials
|
||||
作者：[Lauren Pritchett][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[geekpi](https://github.com/geekpi)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
校对：[wxy](https://github.com/wxy)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: ( )
|
||||
[#]: translator: (messon007)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
|
||||
@ -1,113 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (HankChow)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write effective documentation for your open source project)
|
||||
[#]: via: (https://opensource.com/article/20/3/documentation)
|
||||
[#]: author: (Kevin Xu https://opensource.com/users/kevin-xu)
|
||||
|
||||
How to write effective documentation for your open source project
|
||||
======
|
||||
Documentation quality can make the difference in people trying your
|
||||
project or passing it by.
|
||||
![A pink typewriter][1]
|
||||
|
||||
Unfortunately, good code won't speak for itself. Even the most elegantly designed and well-written codebase that solves the most pressing problem in the world won't just get adopted on its own. You, the open source creator, need to speak for your code and breathe life into your creation. That's where technical writing and documentation come in.
|
||||
|
||||
A project's documentation gets the most amount of traffic, by far. It's the place where people decide whether to continue learning about your project or move on. Thus, spending time and energy on documentation and technical writing, focusing on the most important section, "Getting Started," will do wonders for your project's traction.
|
||||
|
||||
Writing may feel uncomfortable, even daunting, to many of you. As engineers, we are trained more to write code than to write _about_ code. Many people also speak English as a second or even third language and may feel insecure or intimidated about writing in English. (I learned English as a second language, and my mother tongue is Mandarin Chinese, so I feel your pain.)
|
||||
|
||||
But we can't get around the reality that, if you want your project to have a broad, global reach, English is the language you must use. Don't fear. I wrote this post with those challenges in mind. You don't need to be the next Shakespeare to find the advice here useful.
|
||||
|
||||
### Five actionable writing tips
|
||||
|
||||
Here are five actionable writing tips you can apply today. They may seem painfully simple and obvious, yet they are ignored over and over again in technical writing.
|
||||
|
||||
1. **Use** [**active voice**][2]**:** Active voice: "You can change these configurations by…" vs. passive voice: "These configurations can be changed by…"
|
||||
2. **Use simple, short sentences:** While not open source, [Hemingway App][3] and [Grammarly][4] are both helpful tools.
|
||||
3. **Format for easy reading:** Use headings, bullet points, and links to break up information into chunks instead of long explanatory paragraphs.
|
||||
4. **Keep it visual:** Use tables and diagrams, not sentences, to represent information with multiple dimensions.
|
||||
5. **Mind your spelling and grammar:** Always, always, always spell check for typos and grammar check for polish.
|
||||
|
||||
|
||||
|
||||
By applying these tips consistently in your writing and editing workflow, you achieve two big goals: efficient communication and building trust.
|
||||
|
||||
* **Efficient communication:** Engineers don't want to read long-winded, meandering paragraphs in documentation (they have novels for that). They want to get technical information or instructions (when it's a guide) as efficiently as possible. Thus, your writing needs to be lean and useful. (That being said, it's fine to apply some humor, emojis, and "fluff" here and there to give your project some personality and make it more memorable. How exactly you do that will depend on _your_ personality.)
|
||||
* **Building trust:** The most valuable currency you must accrue, especially in the early days of building your project, is trust. Trust comes not only from your code quality but also from the quality of writing that talks about your code. Thus, please apply the same polish to your writing that you would to your code. This is the main reason for point 5 above (on spelling and grammar checks).
|
||||
|
||||
|
||||
|
||||
### Start with Getting Started documentation
|
||||
|
||||
With these fundamental techniques baked into your writing, the section you should spend the most time on in your documentation is the Getting Started section. This is, by far, the most important section and a classic example of the "[80/20 rule][5]" in action. Most of the web traffic to your project lands on your documentation, and most of _that_ lands on Getting Started. If it is well-constructed, you will get a new user right away. If not, the visitor will bounce and likely never come back.
|
||||
|
||||
How do you construct a good Getting Started section? I propose this three-step process:
|
||||
|
||||
1. **Make it a task:** An effective Getting Started guide should be task-oriented—a discrete mini-project that a developer can accomplish. It should _not_ contain too much information about the architectural design, core concept, and other higher-level information. A single, visual architectural overview is fine, but don't devote multiple paragraphs to how and why your project is the best-designed solution. That information belongs somewhere else (more on that below). Instead, the Getting Started section should mostly be a list of steps and commands to… well, get your project started!
|
||||
2. **Can be finished in less than 30 minutes:** The core takeaway here is that the time to completion should be as low as possible; 30 minutes is the upper bound. This time limit also assumes the user has relatively little context about your project. This is important to keep in mind. Most people who bother to go through your Getting Started guide are members of a technical audience with a vague understanding of your project but not much more than that. They are there to try something out before they decide to spend more time digging deeper. "Time to completion" is a metric you should measure to continuously improve your Getting Started guide.
|
||||
3. **Do something meaningful:** What "meaningful" means depends on the open source project. It is important to think hard about what that is, tightly define it into a task, and allow a developer who completes your Getting Started guide to achieve that meaningful task. This meaningful task must speak directly to your project's value; otherwise, it will leave developers feeling like they just wasted their time.
|
||||
|
||||
|
||||
|
||||
For inspiration: If you are a distributed database project, perhaps "meaningful" means the whole cluster remains available with no downtime after you kill some nodes. If you are a data analytics or business intelligence tool, perhaps "meaningful" means quickly generating a dashboard with different visualizations after loading some data. Whatever "meaningful" means to your project, it should be achievable quickly and locally on a laptop.
|
||||
|
||||
A good example is [Linkerd's Getting Started][6]. Linkerd is an open source service mesh for Kubernetes. I'm a novice in Kubernetes and even less familiar with service mesh. Yet, I completed Linkerd's Getting Started guide on my laptop without much hassle, and the experience gave me a taste of what operating a service mesh is all about.
|
||||
|
||||
The three-step process above could be a helpful framework for designing a highly efficient Getting Started section in a measurable way. It is also related to the time-to-value metric when it comes to [productizing your open source project][7].
|
||||
|
||||
### Other core components
|
||||
|
||||
Besides carefully calibrating and optimizing your Getting Started, there are five other top-level components that are necessary to build full-fledged documentation: architectural design, in-production usage guide, use cases, references, and roadmap.
|
||||
|
||||
* **Architectural design:** This is a deep-dive into your project's architecture and the rationales behind your design decisions, full of the details that you strategically glossed over in your Getting Started guide. This section is a big part of your overall [product marketing plan][8]. This section, usually filled with visuals and drawings, is meant to turn a casual hobbyist into an expert enthusiast who is interested in investing time in your project for the long term.
|
||||
* **In-production usage guide:** There is a world of difference between trying something out on a laptop and deploying it in production. Guiding a user who wants to use your project more seriously is an important next step. Demonstrating in-production operational knowledge is also how you attract your initial business customers who may like the promise of the technology but don't know or don't feel confident about using it in a production environment.
|
||||
* **Use cases:** The value of social proof is obvious, so listing your in-production adopters is important. The key here is to make sure this information is easy to find. It will likely be the second most popular link after Getting Started.
|
||||
* **References:** This section explains the project in detail and allows the user to examine and understand it under a microscope. It also functions as a dictionary where people look up information when needed. Some open source creators spend an inordinate amount of time spelling out every nuance and edge case of their project here. The motivation is understandable but unnecessary at the outset when your time is limited. It's more effective to reach a balance between detail and ways to get help: links to your community forum, Stack Overflow tag, or a separate FAQ page would do.
|
||||
* **Roadmap:** Laying out your future vision and plan with a rough timeline will keep users interested and incentivized for the long-term. Your project may not be perfect now, but you have a plan to perfect it. The Roadmap section is also a great place to get your community involved to build a strong ecosystem, so make sure you have a link that tells people how to voice their thoughts and opinions regarding the roadmap. (I'll write about community-building specifics in the future.)
|
||||
|
||||
|
||||
|
||||
You may not have all these components fully fleshed out yet, and some parts may materialize later than others, especially the use cases. However, be intentional about building these out over time. Addressing these five elements is the critical next step to your users' journey into your project, assuming they had a good experience with Getting Started.
|
||||
|
||||
One last note: include a clear one-sentence statement on what license you are using (probably in Getting Started, README, or somewhere else highly visible). This small touch will make vetting your project for adoption from the end user's side much more efficient.
|
||||
|
||||
### Spend 20% of your time writing
|
||||
|
||||
Generally, I recommend spending 10–20% of your time writing. Putting it in context: If you are working on your project full time, it's about half a day to one full day per week.
|
||||
|
||||
The more nuanced point here is you should work writing into your normal workflow, so it becomes a routine, not an isolated chore. Making incremental progress over time, rather than doing all the writing in one giant sitting, is what will help your project reach that ultimate goal: traction and trust.
|
||||
|
||||
* * *
|
||||
|
||||
_Special thanks to [Luc Perkins][9], developer advocate at the Cloud Native Computing Foundation, for his invaluable input._
|
||||
|
||||
_This article originally appeared on_ _[COSS Media][10]_ _and is republished with permission._
|
||||
|
||||
Nigel Babu offers 10 tips for taking your project's documentation to the next level.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/documentation
|
||||
|
||||
作者：[Kevin Xu][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/kevin-xu
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/osdc-docdish-typewriter-pink.png?itok=OXJBtyYf (A pink typewriter)
|
||||
[2]: https://www.grammar-monster.com/glossary/active_voice.htm
|
||||
[3]: http://www.hemingwayapp.com/
|
||||
[4]: https://www.grammarly.com/
|
||||
[5]: https://en.wikipedia.org/wiki/Pareto_principle
|
||||
[6]: https://linkerd.io/2/getting-started/
|
||||
[7]: https://opensource.com/article/19/11/products-open-source-projects
|
||||
[8]: https://opensource.com/article/20/2/product-marketing-open-source-project
|
||||
[9]: https://twitter.com/lucperkins
|
||||
[10]: https://coss.media/open-source-documentation-technical-writing-101/
|
||||
@ -1,179 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to Change MAC Address in Linux)
|
||||
[#]: via: (https://itsfoss.com/change-mac-address-linux/)
|
||||
[#]: author: (Community https://itsfoss.com/author/itsfoss/)
|
||||
|
||||
How to Change MAC Address in Linux
|
||||
======
|
||||
|
||||
Before I show you how to change Mac address in Linux, let’s first discuss why would you change it in the first place.
|
||||
|
||||
You may have several reasons. Maybe you don’t want your actual [MAC address][1] (also called physical address) to be exposed on a public network? Other case can be that the network administrator might have blocked a particular MAC address in the router or firewall.
|
||||
|
||||
One practical ‘benefit’ is that some public network (like Airport WiFi) allows free internet for a limited time. If you want to use the internet beyond that, spoofing your Mac address may trick the network in believing that it’s a new device. It’s a famous meme as well.
|
||||
|
||||
![Airport WiFi Meme][2]
|
||||
|
||||
I am going to show the steps for changing MAC address (also called spoofing/faking MAC address).
|
||||
|
||||
### Changing MAC address in Linux
|
||||
|
||||
Let’s go through each step:
|
||||
|
||||
#### Step 1: Find your MAC address and network interface
|
||||
|
||||
Let’s find out some [details about the network card in Linux][3]. Use this command to get the network interface details:
|
||||
|
||||
```
|
||||
ip link show
|
||||
```
|
||||
|
||||
In the output, you’ll see several details along with the MAC address:
|
||||
|
||||
```
|
||||
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
|
||||
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
|
||||
2: eno1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN mode DEFAULT group default qlen 1000
|
||||
link/ether 94:c6:f8:a7:d7:30 brd ff:ff:ff:ff:ff:ff
|
||||
3: enp0s31f6: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DORMANT group default qlen 1000
|
||||
link/ether 38:42:f8:8b:a7:68 brd ff:ff:ff:ff:ff:ff
|
||||
4: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default
|
||||
link/ether 42:02:07:8f:a7:38 brd ff:ff:ff:ff:ff:ff
|
||||
```
|
||||
|
||||
As you can see, in this case, my network interface is called **enp0s31f6** and its MAC address is **38:42:f8:8b:a7:68**.
|
||||
|
||||
You may want to note it down on a secure place to revert to this original MAC address later on.
|
||||
|
||||
Now you may proceed to changing the MAC address.
|
||||
|
||||
Attention!
|
||||
|
||||
If you do this on a network interface which is currently in use, probably your network connection will be terminated. So either try this method on an additional card or be prepared to restart your network.
|
||||
|
||||
#### Method 1: Change MAC address using Macchanger
|
||||
|
||||
![][4]
|
||||
|
||||
[Macchanger][5] is simple utility to view, modify, and manipulate MAC addresses for your Network interface cards. It is available in almost all GNU/Linux operating systems and you can install is using the package installer of your distribution.
|
||||
|
||||
On Arch Linux or Manjaro:
|
||||
|
||||
```
|
||||
sudo pacman -S macchanger
|
||||
```
|
||||
|
||||
On Fedora, CentOS, RHEL:
|
||||
|
||||
```
|
||||
sudo dnf install macchanger
|
||||
```
|
||||
|
||||
On Debian, Ubuntu, Linux Mint, Kali Linux:
|
||||
|
||||
```
|
||||
sudo apt install macchanger
|
||||
```
|
||||
|
||||
**Important!** You’ll be asked to specify whether macchanger should be set up to run automatically every time a network device is brought up or down. This gives a new MAC address whenever you attach an Ethernet cable or re-enable WiFi.
|
||||
|
||||
![Not a good idea to run it automatically][6]
|
||||
|
||||
I recommend not to run it automatically, unless you really need to change your MAC address every time. So, choose No (by pressing tab key) and hit Enter key to continue.
|
||||
|
||||
##### How to Use Macchanger to change MAC address
|
||||
|
||||
Do you remember your network interface name? You got it in the Step 1 earlier.
|
||||
|
||||
Now, to assign any random MAC address to this network card, use:
|
||||
|
||||
```
|
||||
sudo macchanger -r enp0s31f6
|
||||
```
|
||||
|
||||
After changing the MAC id, verify it using command:
|
||||
|
||||
```
|
||||
ip addr
|
||||
```
|
||||
|
||||
You will now see that MAC has been spoofed.
|
||||
|
||||
To change the MAC address to a specific value, specify any custom MAC address using command:
|
||||
|
||||
```
|
||||
macchanger --mac=XX:XX:XX:XX:XX:XX
|
||||
```
|
||||
|
||||
Where XX:XX:XX:XX:XX:XX is the new MAC id that you want to change.
|
||||
|
||||
Finally, to revert the MAC address to its original hardware value, run the following command:
|
||||
|
||||
```
|
||||
macchanger -p enp0s31f6
|
||||
```
|
||||
|
||||
However, you don’t have to do this. Once you reboot the system, the changes will be automatically lost, and the actual MAC address will be restored again.
|
||||
|
||||
You can always check the man page for more details.
|
||||
|
||||
#### Method 2: Changing Mac address using iproute2 [intermediate knowledge]
|
||||
|
||||
I would recommend using Macchanger but if you don’t want to use it, there is another way to change the MAC address in Linux.
|
||||
|
||||
First, turn off the network card using command:
|
||||
|
||||
```
|
||||
sudo ip link set dev enp0s31f6 down
|
||||
```
|
||||
|
||||
Next, set the new MAC using command:
|
||||
|
||||
```
|
||||
sudo ip link set dev enp0s31f6 address XX:XX:XX:XX:XX:XX
|
||||
```
|
||||
|
||||
Finally, turn the network back on with this command:
|
||||
|
||||
```
|
||||
sudo ip link set dev enp0s31f6 up
|
||||
```
|
||||
|
||||
Now, verify new MAC address:
|
||||
|
||||
```
|
||||
ip link show enp0s31f6
|
||||
```
|
||||
|
||||
That’s it. You have successfully changed the MAC address in true Linux style. Stay tuned with It’s FOSS for more Linux tutorial and tips.
|
||||
|
||||
![][7]
|
||||
|
||||
### Dimitrios Savvopoulos
|
||||
|
||||
Dimitrios is an MSc Mechanical Engineer but a Linux enthusiast in heart. He is well settled in Solus OS but curiosity drives him to constantly test other distros. Challenge is part of his personality and his hobby is to compete from 5k to the marathon distance.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://itsfoss.com/change-mac-address-linux/
|
||||
|
||||
作者：[Community][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://itsfoss.com/author/itsfoss/
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://en.wikipedia.org/wiki/MAC_address
|
||||
[2]: https://i2.wp.com/itsfoss.com/wp-content/uploads/2020/03/airport_wifi_meme.jpg?ssl=1
|
||||
[3]: https://itsfoss.com/find-network-adapter-ubuntu-linux/
|
||||
[4]: https://i1.wp.com/itsfoss.com/wp-content/uploads/2020/03/Change_MAC_Address_Linux.jpg?ssl=1
|
||||
[5]: https://github.com/alobbs/macchanger
|
||||
[6]: https://i2.wp.com/itsfoss.com/wp-content/uploads/2020/03/configuring_mcchanger.jpg?ssl=1
|
||||
[7]: https://i0.wp.com/itsfoss.com/wp-content/uploads/2020/03/Dimitrios.jpg?ssl=1
|
||||
@ -1,5 +1,5 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: ( )
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: ( )
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
|
||||
@ -0,0 +1,106 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (HankChow)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write effective documentation for your open source project)
|
||||
[#]: via: (https://opensource.com/article/20/3/documentation)
|
||||
[#]: author: (Kevin Xu https://opensource.com/users/kevin-xu)
|
||||
|
||||
如何为你的开源项目编写实用的文档
|
||||
======
|
||||
一份优质的文档可以让很多用户对你的项目路人转粉。
|
||||
|
||||
![A pink typewriter][1]
|
||||
|
||||
好的代码很多时候并不代表一切。或许你能用最精巧的代码解决了世界上最迫切需要解决的问题，但如果你作为一个开源开发者，没能用准确的语言将你的作品公之于世，你的代码也只能成为沧海遗珠。因此，技术写作和文档编写是很重要的技能。
|
||||
|
||||
一般来说，项目中的文档是最受人关注的部分，很多用户会通过文档来决定自己是否应该对某个项目开始学习或研究。所以，我们不能忽视技术写作和文档编写的工作，尤其要重点关注其中的“入门”部分，这会对你项目的发展起到关键性的作用。
|
||||
|
||||
对于很多人来说，写作是一件令人厌烦甚至恐惧的事情。我们这些工程师出身的人，学习“写代码”比学习“为代码写文档”明显更多。不少人会把英语作为自己的第二语言或者第三语言，他们可能会对英语写作感到不安全甚至害怕（我的母语是汉语，英语是作为我的第二语言学习的，所以我也能感受到这种痛苦）。
|
||||
|
||||
但如果你希望自己的项目能在全球范围内产生一定的影响力，英语就是你必须使用的语言，这是一个无法避免的现实。但不必害怕，我在写这篇文章的时候就考虑到了这些可能带来的挑战，并给出了我的一些建议。
|
||||
|
||||
### 五条有用的写作建议
|
||||
|
||||
这五条建议你马上就可以用起来，尽管看起来似乎有些浅显，但在技术写作时却经常被忽视。
|
||||
|
||||
1. 使用[主动语态][2]：感受一下主动语态下的“你可以这样更改配置（You can change these configurations by…）”和被动语态下的“配置可以这样更改（These configurations can be changed by…）”有什么不同之处。
|
||||
2. 使用简洁明了的句子：可以借助 [Hemingway App][3] 或者 [Grammarly][4] 这样的工具，尽管它们并不开源。
|
||||
3. 保持条理性：你可以在文档中通过写标题、划重点、引链接等方式，把各类信息划分为不同的部分，避免将所有内容都杂糅在一大段冗长的文字当中。
|
||||
4. 提高可读性：除了单纯的文字之外，运用图表也是从多种角度表达的手段之一。
|
||||
5. 注意拼写和语法：必须记得检查文档中是否有拼写错误或者语法错误。
|
||||
|
||||
只要在文档的写作和编辑过程中应用到这些技巧，你就能够和读者建立起沟通和信任。
|
||||
|
||||
* 高效沟通：对于工程师们来说，阅读长篇大论的冗长文字，还不如去看小说。在阅读技术文档时，他们总是希望能够从中快速准确地获取到有用的信息。因此，技术文档的最佳风格应该是精简而有效的，不过这并不代表文档中不能出现类似幽默、emoji 甚至段子这些东西，这些元素可以当你的文档更有个性、更使人印象深刻。当然，具体的实现方式就因人而异了
|
||||
* 建立信任：你需要取得文档读者们的信任，这在一个项目的前期尤为重要。读者对你的信任除了来源于你代码的质量，还跟你文档编写的质量有关。所以你不仅要打磨代码，还要润色好相关的文档，这也是上面第 5 点建议拼写和语法检查的原因。
|
||||
|
||||
### 如何开始编写文档
|
||||
|
||||
现在，最需要花费功夫的应该就是“入门”部分了，这是一篇技术文档最重要的部分，[二八定律][5]在这里得到了充分体现：访问一个项目的大部分流量都会落在项目文档上，而访问项目文档的大部分流量则会落在文档的“入门”部分中。因此，如果文档的“入门”部分写得足够好，项目就会吸引到很多用户，反之，用户会对你的项目敬而远之。
|
||||
|
||||
那么如何写好“入门”部分呢？我建议按照以下三步走：
|
||||
|
||||
1. 任务化：入门指南应该以任务为导向。这里的任务指的是对于开发者来说可以完成的离散的小项目，而不应该包含太多涉及到体系结构、核心概念等的抽象信息，因此在“入门”部分只需要提供一个简单明了的概述就可以了。也不要在“入门”部分大谈这个项目如何优秀地解决了问题，这个话题可以放在文档中别的部分进行说明。总而言之，“入门”部分最好是给出一些主要的操作步骤，这样显得开门见山。
|
||||
2. 30 分钟内能够完成：这一点的核心是耗时尽可能短，不宜超过 30 分钟，这个时间上限是考虑到用户可能对你的项目并不了解。这一点很重要，大部分愿意浏览文档的人都是有技术基础的，但对你的项目也仅仅是一知半解。首先让这些读者尝试进行一些相关操作，在收到一定效果后，他们才会愿意花更多时间深入研究整个项目。因此，你可以从耗时这个角度来评估你的文档“入门”部分有没有需要改进之处。
|
||||
3. 有意义的任务：这里“有意义”的含义取决于你的开源项目。最重要的是认真思考并将“入门”部分严格定义为一项任务，然后交给你的读者去完成。这个项目的价值应该在这项有意义的任务中有所体现，不然读者可能会感觉这是一个浪费时间的行为。
|
||||
|
||||
提示：假如你的项目是一个分布式数据库，那么达到“整个集群在某些节点故障的情况下可以不中断地保持可用”的目标就可以认为是“有意义”的；加入你的项目是一个数据分析工具或者是商业智能工具，“有意义”的目标也可以是“加载数据后能快速生成多种可视化效果的仪表板”。总之，无论你的项目需要达到什么“有意义”的目标，都应该能在笔记本电脑上本地快速实现。
|
||||
|
||||
[Linkerd 入门][6]就是一个很好的例子。Linkerd 是 Kubernetes 的开源<ruby>服务网格<rt>Service Mesh</rt></ruby>，当时我对 Kubernetes 了解并不多，也不熟悉服务网格。但我在自己的笔记本电脑上很轻松地就完成了其中的任务，同时也加深了对服务网格的理解。
|
||||
|
||||
上面提到的三步过程是一个很有用的框架，对一篇文档“入门”部分的设计和量化评估很有帮助。今后你如果想将你的[开源项目产品化][7]，这个框架还可能对<ruby>实现价值的时间<rt>time-to-value</rt></ruby>产生影响。
|
||||
|
||||
### Other core components
|
||||
|
||||
认真写好“入门”部分之后，你的文档中还需要有这五个部分：架构设计、生产环境使用指导、使用案例、参考资料以及未来展望，这五个部分在一份完整的文档中是必不可少的。
|
||||
|
||||
* 架构设计：这一部分需要深入探讨整个项目架构设计的依据，“入门”部分中一笔带过的那些关键细节就应该在这里体现。在产品化过程中，这个部分将会是[产品推广计划][8]的核心，因此通常会包含一些可视化呈现的内容，期望的效果是让更多用户长期参与到项目中来。
|
||||
* 生产环境使用指导：对于同一个项目，在生产环境中部署比在笔记本电脑上部署要复杂得多。因此，指导用户认真使用就尤为重要。同时，有些用户可能对项目很感兴趣，但对生产环境下的使用有所顾虑，而指导和展示的过程则正好能够吸引到这类潜在的用户。
|
||||
* 使用案例：<ruby>社会认同<rt>social proof</rt></ruby>的力量是有目共睹的，所以很有必要列出正在生产环境使用这个项目的其他用户，并把这些信息摆放在显眼的位置。这个部分的浏览量甚至仅次于“入门”部分。
|
||||
* 参考资料：这个部分是对项目的一些详细说明，让用户得以进行详细的研究以及查阅相关信息。一些开源作者会在这个部分事无巨细地列出项目中的每一个细节和<ruby>边缘情况<rt>edge case</rt></ruby>，这种做法可以理解，但不推荐在项目初期就在这个部分花费过多的时间。你可以采取更折中的方式，在质量和效率之间取得平衡，例如提供一些相关社区的链接、Stack Overflow 上的标签或单独的 FAQ 页面。
|
||||
* 未来展望：你需要制定一个简略的时间表，规划这个项目的未来发展方向，这会让用户长期保持兴趣。尽管项目在当下可能并不完美，但要让用户知道你仍然有完善这个项目的计划。这个部分也能让整个社区构建一个强大的生态，因此还要向用户提供表达他们对未来展望的看法的交流区。
|
||||
|
||||
以上这几个部分或许还没有在你的文档中出现，甚至可能会在后期才能出现，尤其是“使用案例”部分。尽管如此，还是应该在文档中逐渐加入这些部分。如果用户对“入门”部分已经感觉良好，那以上这几个部分将会提起用户更大的兴趣。
|
||||
|
||||
最后，请在“入门”部分、README 文件或其它显眼的位置注明整个项目所使用的许可证。这个细节会让你的项目更容易通过终端用户的审核。
|
||||
|
||||
### 花 20% 的时间写作
|
||||
|
||||
一般情况下，我建议把整个项目 10% 到 20% 的时间用在文档写作上。也就是说，如果你是全职进行某一个项目的，文档写作需要在其中占半天到一天。
|
||||
|
||||
再细致一点，应该将写作纳入到常规的工作流程中，这样它就不再是一件孤立的琐事，而是日常的事务。文档写作应该随着工作进度同步进行，切忌将所有写作任务都堆积起来最后完成，这样才可以帮助你的项目达到最终目标：吸引用户、获得信任。
|
||||
|
||||
* * *
|
||||
|
||||
_特别鸣谢云原生计算基金会的布道师 [Luc Perkins][9] 给出的宝贵意见。_
|
||||
|
||||
_本文首发于_ _[COSS Media][10]_ _并经许可发布。_
|
||||
|
||||
Nigel Babu 提供了 10 条帮助编写项目文档的有用技巧。
|
||||
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/documentation
|
||||
|
||||
作者：[Kevin Xu][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[HankChow](https://github.com/HankChow)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/kevin-xu
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/osdc-docdish-typewriter-pink.png?itok=OXJBtyYf (A pink typewriter)
|
||||
[2]: https://www.grammar-monster.com/glossary/active_voice.htm
|
||||
[3]: http://www.hemingwayapp.com/
|
||||
[4]: https://www.grammarly.com/
|
||||
[5]: https://en.wikipedia.org/wiki/Pareto_principle
|
||||
[6]: https://linkerd.io/2/getting-started/
|
||||
[7]: https://opensource.com/article/19/11/products-open-source-projects
|
||||
[8]: https://opensource.com/article/20/2/product-marketing-open-source-project
|
||||
[9]: https://twitter.com/lucperkins
|
||||
[10]: https://coss.media/open-source-documentation-technical-writing-101/
|
||||
179
translated/tech/20200313 How to Change MAC Address in Linux.md
Normal file
179
translated/tech/20200313 How to Change MAC Address in Linux.md
Normal file
@ -0,0 +1,179 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to Change MAC Address in Linux)
|
||||
[#]: via: (https://itsfoss.com/change-mac-address-linux/)
|
||||
[#]: author: (Community https://itsfoss.com/author/itsfoss/)
|
||||
|
||||
如何在 Linux 中更改 MAC 地址
|
||||
======
|
||||
|
||||
在向你展示如何在 Linux 中更改 Mac 地址之前，让我们首先讨论为什么要更改它。
|
||||
|
||||
可能有几个原因。也许你不希望在公共网络上公开你的实际 [MAC 地址][1]（也称为物理地址）？还有可能是网络管理员可能已在路由器或防火墙中阻止了特定的 MAC 地址。
|
||||
|
||||
一个实用的“好处”是某些公共网络（例如机场 WiFi）允许在有限的时间内免费上网。如果你还想继续使用，那么伪造 Mac 地址可能会欺骗网络，让它认为是一台新设备。这也是一个有名的原因。
|
||||
|
||||
![Airport WiFi Meme][2]
|
||||
|
||||
我将展示更改 MAC 地址（也称为欺骗/伪造 MAC 地址）的步骤。
|
||||
|
||||
### 在 Linux 中更改 MAC 地址
|
||||
|
||||
让我们一步步来：
|
||||
|
||||
#### 步骤 1：查找你的 MAC 地址和网络接口
|
||||
|
||||
让我们找出一些[关于 Linux 中网卡的细节][3]。使用此命令获取网络接口详细信息：
|
||||
|
||||
```
|
||||
ip link show
|
||||
```
|
||||
|
||||
在输出中，你将看到一些详细信息以及 MAC 地址：
|
||||
|
||||
```
|
||||
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
|
||||
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
|
||||
2: eno1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN mode DEFAULT group default qlen 1000
|
||||
link/ether 94:c6:f8:a7:d7:30 brd ff:ff:ff:ff:ff:ff
|
||||
3: enp0s31f6: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DORMANT group default qlen 1000
|
||||
link/ether 38:42:f8:8b:a7:68 brd ff:ff:ff:ff:ff:ff
|
||||
4: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default
|
||||
link/ether 42:02:07:8f:a7:38 brd ff:ff:ff:ff:ff:ff
|
||||
```
|
||||
|
||||
如你所见，在这里，我的网络接口称为 **enp0s31f6**，MAC 地址为 **38:42:f8:8b:a7:68**。
|
||||
|
||||
你可能需要在安全的地方记录下来，以便稍后还原到该原始 MAC 地址。
|
||||
|
||||
现在你可以继续更改MAC地址。
|
||||
|
||||
注意！
|
||||
|
||||
如果在当前使用的网络接口上执行此操作，那么可能会中断你的网络连接。因此，请在其他网卡上尝试使用此方法，或者准备重启网络。
|
||||
|
||||
#### 方法 1：使用 Macchanger 更改 MAC 地址
|
||||
|
||||
![][4]
|
||||
|
||||
[Macchanger][5] 是查看、修改和操作网卡 MAC 地址的简单程序。它几乎在所有 GNU/Linux 操作系统中都可用，你可以使用发行版的包安装程序进行安装。
|
||||
|
||||
在 Arch Linux 或 Manjaro 上：
|
||||
|
||||
```
|
||||
sudo pacman -S macchanger
|
||||
```
|
||||
|
||||
在 Fedora、CentOS 和 RHEL 上：
|
||||
|
||||
```
|
||||
sudo dnf install macchanger
|
||||
```
|
||||
|
||||
在 Debian、Ubuntu、Linux Mint、Kali Linux 上：
|
||||
|
||||
```
|
||||
sudo apt install macchanger
|
||||
```
|
||||
|
||||
**重要！**系统会要求你选择是否应将 macchanger 设置为在每次启动或关闭网络设备时自动运行。每当你接到网线或重启 WiFi 时，它都会提供一个新的 MAC 地址。
|
||||
|
||||
![Not a good idea to run it automatically][6]
|
||||
|
||||
我建议不要自动运行它，除非你确实需要每次更改 MAC 地址。因此，选择 No（按 Tab 键），然后按回车键继续。
|
||||
|
||||
##### 如何使用 Macchanger 更改 MAC 地址
|
||||
|
||||
你还记得网络接口名称吗？你在前面的步骤 1 中获得了它。
|
||||
|
||||
现在，要将随机 MAC 地址分配给该网卡，请使用：
|
||||
|
||||
```
|
||||
sudo macchanger -r enp0s31f6
|
||||
```
|
||||
|
||||
更改 MAC 后，使用以下命令进行验证：
|
||||
|
||||
```
|
||||
ip addr
|
||||
```
|
||||
|
||||
现在你将看到已经伪造 MAC。
|
||||
|
||||
要将 MAC 地址更改为特定值，请使用以下命令指定自定义 MAC 地址：
|
||||
|
||||
```
|
||||
macchanger --mac=XX:XX:XX:XX:XX:XX
|
||||
```
|
||||
|
||||
其中 XX:XX:XX:XX:XX:XX 是你要更改的新 MAC。
|
||||
|
||||
最后，要将 MAC 地址恢复为其原始硬件值，请运行以下命令：
|
||||
|
||||
```
|
||||
macchanger -p enp0s31f6
|
||||
```
|
||||
|
||||
但是，你不必如此。重启系统后，更改将自动丢失，并且实际的 MAC 地址将再次恢复。
|
||||
|
||||
你可以随时查看手册页以获取更多详细信息。
|
||||
|
||||
#### 方法 2：使用 iproute2 更改 Mac 地址（中级知识）
|
||||
|
||||
我建议你使用 Macchanger，但如果你不想使用它，那么可以使用另一种方法在 Linux 中更改 MAC 地址。
|
||||
|
||||
首先，使用以下命令关闭网卡：
|
||||
|
||||
```
|
||||
sudo ip link set dev enp0s31f6 down
|
||||
```
|
||||
|
||||
接下来，使用以下命令设置新的 MAC：
|
||||
|
||||
```
|
||||
sudo ip link set dev enp0s31f6 address XX:XX:XX:XX:XX:XX
|
||||
```
|
||||
|
||||
最后，使用以下命令重新打开网络：
|
||||
|
||||
```
|
||||
sudo ip link set dev enp0s31f6 up
|
||||
```
|
||||
|
||||
现在，验证新的 MAC 地址：
|
||||
|
||||
```
|
||||
ip link show enp0s31f6
|
||||
```
|
||||
|
||||
就是这些了。你已经成功地在 Linux 中修改了 MAC 地址。敬请期待 FOSS 更多有关 Linux 教程和技巧的文章。
|
||||
|
||||
![][7]
|
||||
|
||||
### Dimitrios Savvopoulos
|
||||
|
||||
Dimitrios 是一名机械工程硕士，但对 Linux 十分热爱。他一直使用 Solus OS，但在好奇心驱使他不断地测试其他发行版。挑战是他个性的一部分，他的业余爱好是 5 公里到马拉松距离的比赛。
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://itsfoss.com/change-mac-address-linux/
|
||||
|
||||
作者：[Community][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[geekpi](https://github.com/geekpi)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://itsfoss.com/author/itsfoss/
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://en.wikipedia.org/wiki/MAC_address
|
||||
[2]: https://i2.wp.com/itsfoss.com/wp-content/uploads/2020/03/airport_wifi_meme.jpg?ssl=1
|
||||
[3]: https://itsfoss.com/find-network-adapter-ubuntu-linux/
|
||||
[4]: https://i1.wp.com/itsfoss.com/wp-content/uploads/2020/03/Change_MAC_Address_Linux.jpg?ssl=1
|
||||
[5]: https://github.com/alobbs/macchanger
|
||||
[6]: https://i2.wp.com/itsfoss.com/wp-content/uploads/2020/03/configuring_mcchanger.jpg?ssl=1
|
||||
[7]: https://i0.wp.com/itsfoss.com/wp-content/uploads/2020/03/Dimitrios.jpg?ssl=1
|
||||
Loading…
Reference in New Issue
Block a user