mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-02-06 23:50:16 +08:00
Merge remote-tracking branch 'LCTT/master'
This commit is contained in:
Xingyu Wang
commit
b96d3d0bc6
@ -0,0 +1,70 @@
|
|||||||
|
[#]: collector: (lujun9972)
|
||||||
|
[#]: translator: ( )
|
||||||
|
[#]: reviewer: ( )
|
||||||
|
[#]: publisher: ( )
|
||||||
|
[#]: url: ( )
|
||||||
|
[#]: subject: (Hypervisor comeback, Linus says no and reads email, and more industry trends)
|
||||||
|
[#]: via: (https://opensource.com/article/19/11/hypervisor-stable-kernel-and-more-industry-trends)
|
||||||
|
[#]: author: (Tim Hildred https://opensource.com/users/thildred)
|
||||||
|
|
||||||
|
Hypervisor comeback, Linus says no and reads email, and more industry trends
|
||||||
|
======
|
||||||
|
A weekly look at open source community and industry trends.
|
||||||
|
![Person standing in front of a giant computer screen with numbers, data][1]
|
||||||
|
|
||||||
|
As part of my role as a senior product marketing manager at an enterprise software company with an open source development model, I publish a regular update about open source community, market, and industry trends for product marketers, managers, and other influencers. Here are five of my and their favorite articles from that update.
|
||||||
|
|
||||||
|
## [Containers in 2019: They're calling it a [hypervisor] comeback][2]
|
||||||
|
|
||||||
|
> So what does all this mean as we continue with rapid adoption and hyper-ecosystem growth around Kubernetes and containers? Let’s try and break that down into a few key areas and see what all the excitement is about.
|
||||||
|
|
||||||
|
**The impact**: I'm pretty sure that the title of the article is an LL Cool J reference, which I wholeheartedly approve of. Even more important though is a robust unpacking of developments in the hypervisor space over the last year and how they square up against the trend towards cloud-native and container-based development.
|
||||||
|
|
||||||
|
## [Linux kernel is getting more reliable, says Linus Torvalds. Plus: What do you need to do to be him?][3]
|
||||||
|
|
||||||
|
> "In the end my job is to say no. Somebody has to be able to say no, because other developers know that if they do something bad I will say no. They hopefully in turn are more careful. But in order to be able to say no, I have to know the background, because otherwise I can't do my job. I spend all my time basically reading email about what people are working on.
|
||||||
|
|
||||||
|
**The impact**: The rehabilitation of Linus as a much chiller guy continues; this one has some good advice for people leading distributed teams.
|
||||||
|
|
||||||
|
## [Automated infrastructure in the on-premise datacenter—OpenShift 4.2 on OpenStack 15 (Stein)][4]
|
||||||
|
|
||||||
|
> Up until now IPI (Installer Provision Infrastructure) has only supported public clouds: AWS, Azure, and Google. Now with OpenShift 4.2 it is supporting OpenStack. For the first time we can bring IPI into the on-premise datacenter where it is IMHO most needed. This single feature has the potential to revolutionize on-premise environments and bring them into the cloud-age with a single click and that promise is truly something to get excited about!
|
||||||
|
|
||||||
|
**The impact**: So much tech press has started with the assumption that every company should run their infrastructure like a hyperscaler. The technology is catching up to make the user experience of that feasible.
|
||||||
|
|
||||||
|
## [Kubernetes autoscaling 101: Cluster autoscaler, horizontal autoscaler, and vertical pod autoscaler][5]
|
||||||
|
|
||||||
|
> I’m providing in this post a high-level overview of different scalability mechanisms inside Kubernetes and best ways to make them serve your needs. Remember, to truly master Kubernetes, you need to master different ways to manage the scale of cluster resources, that’s [the core of promise of Kubernetes][6].
|
||||||
|
>
|
||||||
|
> _Configuring Kubernetes clusters to balance resources and performance can be challenging, and requires expert knowledge of the inner workings of Kubernetes. Just because your app or services’ workload isn’t constant, it rather fluctuates throughout the day if not the hour. Think of it as a journey and ongoing process._
|
||||||
|
|
||||||
|
**The impact**: You can tell whether someone knows what they're talking about if they can represent it in a simple diagram. Thanks to the excellent diagrams in this post, I know more day 2 concerns of Kubernetes operators than I ever wanted to.
|
||||||
|
|
||||||
|
## [GitHub: All open source developers anywhere are welcome][7]
|
||||||
|
|
||||||
|
> Eighty percent of all open-source contributions today, come from outside of the US. The top two markets for open source development outside of the US are China and India. These markets, although we have millions of developers in them, are continuing to grow faster than any others at about 30% year-over-year average.
|
||||||
|
|
||||||
|
**The impact**: One of my open source friends likes to muse on the changing culture within the open source community. He posits that the old guard gatekeepers are already becoming irrelevant. I don't know if I completely agree, but I think you can look at the exponentially increasing contributions from places that haven't been on the open source map before and safely speculate that the open source culture of tomorrow will be radically different than that of today.
|
||||||
|
|
||||||
|
_I hope you enjoyed this list of what stood out to me from last week and come back next Monday for more open source community, market, and industry trends._
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
via: https://opensource.com/article/19/11/hypervisor-stable-kernel-and-more-industry-trends
|
||||||
|
|
||||||
|
作者：[Tim Hildred][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/thildred
|
||||||
|
[b]: https://github.com/lujun9972
|
||||||
|
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/data_metrics_analytics_desktop_laptop.png?itok=9QXd7AUr (Person standing in front of a giant computer screen with numbers, data)
|
||||||
|
[2]: https://www.infoq.com/articles/containers-hypervisors-2019/
|
||||||
|
[3]: https://www.theregister.co.uk/2019/10/30/linux_kernel_is_getting_more_reliable_says_linus_torvalds/
|
||||||
|
[4]: https://keithtenzer.com/2019/10/29/automated-infrastructure-in-the-on-premise-datacenter-openshift-4-2-on-openstack-15-stein/
|
||||||
|
[5]: https://www.cncf.io/blog/2019/10/29/kubernetes-autoscaling-101-cluster-autoscaler-horizontal-autoscaler-and-vertical-pod-autoscaler/
|
||||||
|
[6]: https://speakerdeck.com/thockin/everything-you-ever-wanted-to-know-about-resource-scheduling-dot-dot-dot-almost
|
||||||
|
[7]: https://www.zdnet.com/article/github-all-open-source-developers-anywhere-are-welcome/#ftag=RSSbaffb68
|
||||||
@ -0,0 +1,92 @@
|
|||||||
|
[#]: collector: (lujun9972)
|
||||||
|
[#]: translator: ( )
|
||||||
|
[#]: reviewer: ( )
|
||||||
|
[#]: publisher: ( )
|
||||||
|
[#]: url: ( )
|
||||||
|
[#]: subject: (Red Hat announces RHEL 8.1 with predictable release cadence)
|
||||||
|
[#]: via: (https://www.networkworld.com/article/3451367/red-hat-announces-rhel-8-1-with-predictable-release-cadence.html)
|
||||||
|
[#]: author: (Sandra Henry-Stocker https://www.networkworld.com/author/Sandra-Henry_Stocker/)
|
||||||
|
|
||||||
|
Red Hat announces RHEL 8.1 with predictable release cadence
|
||||||
|
======
|
||||||
|
|
||||||
|
[Clkr / Pixabay][1] [(CC0)][2]
|
||||||
|
|
||||||
|
[Red Hat][3] has just today announced the availability of Red Hat Enterprise Linux (RHEL) 8.1, promising improvements in manageability, security and performance.
|
||||||
|
|
||||||
|
RHEL 8.1 will enhance the company’s open [hybrid-cloud][4] portfolio and continue to provide a consistent user experience between on-premises and public-cloud deployments.
|
||||||
|
|
||||||
|
[[Get regularly scheduled insights by signing up for Network World newsletters.]][5]
|
||||||
|
|
||||||
|
RHEL 8.1 is also the first release that will follow what Red Hat is calling its "predictable release cadence". Announced at Red Hat Summit 2019, this means that minor releases will be available every six months. The expectation is that this rhythmic release cycle will make it easier both for customer organizations and other software providers to plan their upgrades.
|
||||||
|
|
||||||
|
[][6]
|
||||||
|
|
||||||
|
BrandPost Sponsored by HPE
|
||||||
|
|
||||||
|
[Take the Intelligent Route with Consumption-Based Storage][6]
|
||||||
|
|
||||||
|
Combine the agility and economics of HPE storage with HPE GreenLake and run your IT department with efficiency.
|
||||||
|
|
||||||
|
Red Hat Enterprise Linux 8.1 provides product enhancements in many areas.
|
||||||
|
|
||||||
|
### Enhanced automation
|
||||||
|
|
||||||
|
All supported RHEL subscriptions now include access to Red Hat's proactive analytics, **Red Hat Insights**. With more than 1,000 rules for operating RHEL systems whether on-premises or cloud deployments, Red Hat Insights help IT administrators flag potential configuration, security, performance, availability and stability issues before they impact production.
|
||||||
|
|
||||||
|
### New system roles
|
||||||
|
|
||||||
|
RHEL 8.1 streamlines the process for setting up subsystems to handle specific functions such as storage, networking, time synchronization, kdump and SELinux. This expands on the variety of Ansible system roles.
|
||||||
|
|
||||||
|
### Live kernel patching
|
||||||
|
|
||||||
|
RHEL 8.1 adds full support for live kernel patching. This critically important feature allows IT operations teams to deal with ongoing threats without incurring excessive system downtime. Kernel updates can be applied to remediate common vulnerabilities and exposures (CVE) while reducing the need for a system reboot. Additional security enhancements include enhanced CVE remediation, kernel-level memory protection and application whitelisting.
|
||||||
|
|
||||||
|
### Container-centric SELinux profiles
|
||||||
|
|
||||||
|
These profiles allow the creation of more tailored security policies to control how containerized services access host-system resources, making it easier to harden systems against security threats.
|
||||||
|
|
||||||
|
### Enhanced hybrid-cloud application development
|
||||||
|
|
||||||
|
A reliably consistent set of supported development tools is included, among them the latest stable versions of popular open-source tools and languages like golang and .NET Core as well as the ability to power modern data-processing workloads such as Microsoft SQL Server and SAP solutions.
|
||||||
|
|
||||||
|
Red Hat Linux 8.1 is available now for RHEL subscribers via the [Red Hat Customer Portal][7]. Red Hat Developer program members may obtain the latest releases at no cost at the [Red Hat Developer][8] site.
|
||||||
|
|
||||||
|
#### Additional resources
|
||||||
|
|
||||||
|
Here are some links to additional information:
|
||||||
|
|
||||||
|
* More about [Red Hat Enterprise Linux][9]
|
||||||
|
* Get a [RHEL developer subscription][10]
|
||||||
|
* More about the latest features at [Red Hat Insights][11]
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Join the Network World communities on [Facebook][12] and [LinkedIn][13] to comment on topics that are top of mind.
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
via: https://www.networkworld.com/article/3451367/red-hat-announces-rhel-8-1-with-predictable-release-cadence.html
|
||||||
|
|
||||||
|
作者：[Sandra Henry-Stocker][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://www.networkworld.com/author/Sandra-Henry_Stocker/
|
||||||
|
[b]: https://github.com/lujun9972
|
||||||
|
[1]: https://pixabay.com/vectors/red-hat-fedora-fashion-style-26734/
|
||||||
|
[2]: https://creativecommons.org/publicdomain/zero/1.0/
|
||||||
|
[3]: https://www.networkworld.com/article/3316960/ibm-closes-34b-red-hat-deal-vaults-into-multi-cloud.html
|
||||||
|
[4]: https://www.networkworld.com/article/3268448/what-is-hybrid-cloud-really-and-whats-the-best-strategy.html
|
||||||
|
[5]: https://www.networkworld.com/newsletters/signup.html
|
||||||
|
[6]: https://www.networkworld.com/article/3440100/take-the-intelligent-route-with-consumption-based-storage.html?utm_source=IDG&utm_medium=promotions&utm_campaign=HPE20773&utm_content=sidebar ( Take the Intelligent Route with Consumption-Based Storage)
|
||||||
|
[7]: https://access.redhat.com/
|
||||||
|
[8]: https://developer.redhat.com
|
||||||
|
[9]: https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux
|
||||||
|
[10]: https://developers.redhat.com/
|
||||||
|
[11]: https://www.redhat.com/en/blog/whats-new-red-hat-insights-november-2019
|
||||||
|
[12]: https://www.facebook.com/NetworkWorld/
|
||||||
|
[13]: https://www.linkedin.com/company/network-world
|
||||||
@ -0,0 +1,57 @@
|
|||||||
|
[#]: collector: (lujun9972)
|
||||||
|
[#]: translator: ( )
|
||||||
|
[#]: reviewer: ( )
|
||||||
|
[#]: publisher: ( )
|
||||||
|
[#]: url: ( )
|
||||||
|
[#]: subject: (System76 introduces laptops with open source BIOS coreboot)
|
||||||
|
[#]: via: (https://opensource.com/article/19/11/coreboot-system76-laptops)
|
||||||
|
[#]: author: (Don Watkins https://opensource.com/users/don-watkins)
|
||||||
|
|
||||||
|
System76 introduces laptops with open source BIOS coreboot
|
||||||
|
======
|
||||||
|
The company answers open hardware fans by revealing two laptops powered
|
||||||
|
with open source firmware coreboot.
|
||||||
|
![Guy on a laptop on a building][1]
|
||||||
|
|
||||||
|
In mid-October, [System76][2] made an exciting announcement for open source hardware fans: It would soon begin shipping two of its laptop models, [Galago Pro][3] and [Darter Pro][4], with the open source BIOS [coreboot][5].
|
||||||
|
|
||||||
|
The coreboot project [says][6] its open source firmware "is a replacement for your BIOS / UEFI with a strong focus on boot speed, security, and flexibility. It is designed to boot your operating system as fast as possible without any compromise to security, with no back doors, and without any cruft from the '80s." Coreboot was previously known as LinuxBIOS, and the engineers who work on coreboot have also contributed to the Linux kernel.
|
||||||
|
|
||||||
|
Most firmware on computers sold today is proprietary, which means even if you are running an open source operating system, you have no access to your machine's BIOS. This is not so with coreboot. Its developers share the improvements they make, rather than keeping them secret from other vendors. Coreboot's source code can be inspected, learned from, and modified, just like any other open source code.
|
||||||
|
|
||||||
|
[Joshua Woolery][7], marketing director at System76, says coreboot differs from a proprietary BIOS in several important ways. "Traditional firmware is closed source and impossible to review and inspect. It's bloated with unnecessary features and unnecessarily complex [ACPI][8] implementations that lead to PCs operating in unpredictable ways. System76 Open Firmware, on the other hand, is lightweight, fast, and cleanly written." This means your computer boots faster and is more secure, he says.
|
||||||
|
|
||||||
|
I asked Joshua about the impact of coreboot on open hardware overall. "The combination of open hardware and open firmware empowers users beyond what's possible when one or the other is proprietary," he says. "Imagine an open hardware controller like [System76's] [Thelio Io][9] without open source firmware. One could read the schematic and write software to control it, but why? With open firmware, the user starts from functioning hardware and software and can expand from there. Open hardware and firmware enable the community to learn from, adapt, and expand on our work, thus moving technology forward as a whole rather than requiring individuals to constantly re-implement what's already been accomplished."
|
||||||
|
|
||||||
|
Joshua says System76 is working to open source all aspects of the computer, and we will see coreboot on other System76 machines. The hardware and firmware in Thelio Io, the controller board in the company's Thelio desktops, are both open. Less than a year after System76 introduced Thelio, the company is now marketing two laptops with open firmware.
|
||||||
|
|
||||||
|
If you would like to see System76's firmware contributions to the coreboot project, visit the code repository on [GitHub][10]. You can also see the schematics for any supported System76 model by sending an [email][11] with the subject line: _Schematics for <MODEL>_. (Bear in mind that the only currently supported models are darp6 and galp4.) Using the coreboot firmware on other devices is not supported and may render them inoperable,
|
||||||
|
|
||||||
|
Coreboot is licensed under the GNU Public License. You can view the [documentation][12] on the project's website and find out how to [contribute][13] to the project on GitHub.
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
via: https://opensource.com/article/19/11/coreboot-system76-laptops
|
||||||
|
|
||||||
|
作者：[Don Watkins][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/don-watkins
|
||||||
|
[b]: https://github.com/lujun9972
|
||||||
|
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/computer_code_programming_laptop.jpg?itok=ormv35tV (Guy on a laptop on a building)
|
||||||
|
[2]: https://opensource.com/article/19/5/system76-secret-sauce
|
||||||
|
[3]: https://system76.com/laptops/galago
|
||||||
|
[4]: https://system76.com/laptops/darter
|
||||||
|
[5]: https://www.coreboot.org/
|
||||||
|
[6]: https://www.coreboot.org/users.html
|
||||||
|
[7]: https://www.linkedin.com/in/joshuawoolery
|
||||||
|
[8]: https://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface
|
||||||
|
[9]: https://opensource.com/article/18/11/system76-thelio-desktop-computer
|
||||||
|
[10]: https://github.com/system76/firmware-open
|
||||||
|
[11]: mailto:productdev@system76.com
|
||||||
|
[12]: https://doc.coreboot.org/index.html
|
||||||
|
[13]: https://github.com/coreboot/coreboot
|
||||||
@ -0,0 +1,155 @@
|
|||||||
|
[#]: collector: (lujun9972)
|
||||||
|
[#]: translator: ( )
|
||||||
|
[#]: reviewer: ( )
|
||||||
|
[#]: publisher: ( )
|
||||||
|
[#]: url: ( )
|
||||||
|
[#]: subject: (Conquering documentation challenges on a massive project)
|
||||||
|
[#]: via: (https://opensource.com/article/19/11/documentation-challenges-tom-caswell-matplotlib)
|
||||||
|
[#]: author: (Gina Helfrich, Ph.D. https://opensource.com/users/ginahelfrich)
|
||||||
|
|
||||||
|
Conquering documentation challenges on a massive project
|
||||||
|
======
|
||||||
|
Learn more about documentation at scale in this interview with Tom
|
||||||
|
Caswell, Matplotlib lead developer.
|
||||||
|
![Files in a folder][1]
|
||||||
|
|
||||||
|
Given the recent surge in popularity of open source data science projects like pandas, NumPy, and [Matplotlib][2], it’s probably no surprise that the increased level of interest is generating user complaints about documentation. To help shed light on what’s at stake, we talked to someone who knows a lot about the subject: [Thomas Caswell][3], the lead developer of Matplotlib.
|
||||||
|
|
||||||
|
Matplotlib is a flexible and customizable tool for producing static and interactive data visualizations since 2001 and is a foundational project in the scientific Python stack. Matplotlib became a [NumFOCUS-sponsored project][4] in 2015.
|
||||||
|
|
||||||
|
Tom has been working on Matplotlib for the past five years and got his start answering questions about the project on Stack Overflow. Answering questions became submitting bug reports, which became writing patches, which became maintaining the project, which ultimately led to him becoming the lead developer.
|
||||||
|
|
||||||
|
**Fun fact:** Tom’s advancement through the open source community follows exactly the [path described by Brett Cannon][5], a core Python maintainer.
|
||||||
|
|
||||||
|
NumFOCUS Communications Director, Gina Helfrich, sat down with Tom to discuss the challenges of managing documentation on a project as massive and as fundamental as Matplotlib.
|
||||||
|
|
||||||
|
**Gina Helfrich:** Thanks so much for taking the time to talk with us about Matplotlib and open source documentation, Tom. To contextualize our conversation a bit, can you speak a little to your impression of the [back-and-forth][6] on Twitter with Wes McKinney about pandas and user complaints about the documentation?
|
||||||
|
|
||||||
|
**Thomas Caswell:** I only kind of saw the edges, but I see both sides. On one hand, I think something Mike Pope said was, "if it’s not documented, it doesn’t exist." If you are writing open source tools,
|
||||||
|
|
||||||
|
part of that work is documenting them, and doing so clearly in a way that users can discover and actually use, short of going to the source [code]. It’s not good enough to dump code on the internet—you have to do the whole thing.
|
||||||
|
|
||||||
|
On the other hand, if you’re not paying [for the software], you don’t get to make demands. The attitude I think Wes was reacting to, which you see a lot, is: "You built this tool that is useful to me, therefore I expect enterprise-grade paid support because it’s obviously critical to what I’m doing."
|
||||||
|
|
||||||
|
But I think the part Eric O. Lebigot was responding to is the first part. Part of building a tool is the documentation, not just the code. But Wes is responding to the entitlement, the expectation of free work, so I see both sides.
|
||||||
|
|
||||||
|
**GH:** Looking at Matplotlib specifically, which is facing many of the same issues as pandas, I know you have some big challenges with your documentation. I get the impression that there’s this notion out there from new users that getting started with Matplotlib is super frustrating and the docs don’t really help. Can you tell me about the history there and how the project came to have this problem?
|
||||||
|
|
||||||
|
**TC:** So, Matplotlib is a humongous library. I’ve been working on it for five years, and around once a month (or every other month), there’s a bug report where my first reaction is, "Wait… we do _what_?"
|
||||||
|
|
||||||
|
A lot of the library is under-documented. This library survived at least two generations of partial conversion to standardized docstring formats. As I understand it (I wasn’t around at the time), we were one of the first projects outside of core Python to adopt Sphinx to build our docs—possibly a little too early. We have a lot of weird customizations since Sphinx didn’t have those features yet [at the time]. Other people have built better versions of those features since then, but because Matplotlib is so huge, migrating them is hard.
|
||||||
|
|
||||||
|
I think if you build the PDF version of our docs, it’s around 3,000 pages, and I would say that the library has maybe half the documentation it really needs.
|
||||||
|
|
||||||
|
We are woefully under-documented in the sense that not every feature has good docs. On the other hand, we are over-documented in that what we have is not well organized and there’s no clear entry point. If I want to find out how to do something, even I have a hard time finding where something is documented. And if _I_ [the lead developer] have issues finding that information, there’s no prayer of new users finding it. So in that sense, we are both drastically under-documented and drastically over-documented.
|
||||||
|
|
||||||
|
**[Read next: [Syadmins: Poor documentation is not a job insurance strategy][7]]**
|
||||||
|
|
||||||
|
**GH:** Given that Matplotlib is over 15 years old, do you have a sense of who has been writing the documentation? How does your documentation actually get developed?
|
||||||
|
|
||||||
|
**TC:** Historically, much like the code, the documentation was organically developed. We’ve had a lot of investment in examples and docstrings, and a few entries labeled as tutorials that teach you one specific skill. For example, we’ve got prose on the "rough theory of colormaps," and how to make a colormap.
|
||||||
|
|
||||||
|
A lot of Matplotlib’s documentation is examples, and the examples overlap. Over the past few years, when I see interesting examples go by on the mailing list or on Stack Overflow, I’ll say, "Can you put this example in the docs?" So, I guess I’ve been actively contributing to the problem that there’s too much stuff to wade through.
|
||||||
|
|
||||||
|
Part of the issue is that people will do a six-hour tutorial and then some of those examples end up in the docs. Then, someone _else_ will do a six-hour tutorial (you can’t cover the whole library in six hours) and the basics are probably similar, but they may format the tutorial differently.
|
||||||
|
|
||||||
|
**GH:** Wow, that sounds pretty challenging to inherit and try to maintain. What kinds of improvements have you been working on for the documentation?
|
||||||
|
|
||||||
|
**TC:** There’s been an effort over the past couple of years to move to numpydoc format, away from the home-grown scheme we had previously. Also, [Nelle Varoquaux][8] recently did a tremendous amount of work and led the effort to move from how we were doing examples to using Sphinx-Gallery, which makes it much easier to put good prose into examples. This practice was picked up by [Chris Holdgraf][9] recently, as well. Sphinx-Gallery went live on our main docs with Matplotlib 2.1, which was a huge improvement for users. Nelle also organized a distributed [docathon][10].
|
||||||
|
|
||||||
|
We’ve been trying to get better about new features. When there’s a new feature, you must add an example to the docs for that feature, which helps make things discoverable. We’ve been trying to get better about making sure docstrings exist, are accurate, and that they document all of the parameters.
|
||||||
|
|
||||||
|
**GH:** If you could wave a magic wand and have the Matplotlib docs that you want, what would they look like?
|
||||||
|
|
||||||
|
**TC:** Well, as I mentioned, the docs grew organically, and that means we have no consistent voice across them. It also means there’s no single point of truth for various things. When you write an example, how far back down the basics do you go? So, it’s not clear what you need to know before you can understand the example. Either you explain just enough, all the way back (so we’ve got a random assortment of the basics smeared everywhere), or you have examples that, unless you’re already a heavy user, make no sense.
|
||||||
|
|
||||||
|
So, to answer the question, having someone who can actually _write_ and has empathy for users go through and write a 200-page intro to Matplotlib book, and have that be the main entry to the docs. That’s my current vision of what I want.
|
||||||
|
|
||||||
|
**GH:** If you were introducing a new user to Matplotlib today, what would you have her read? Where would you point her in the docs?
|
||||||
|
|
||||||
|
**TC:** Well, there isn’t a good, clear option for, "You’ve been told you need to use Matplotlib. Go spend an afternoon and read this." I’m not sure where I’d point people to for that right now. [Nicolas Rougier][11] has written some [good][12] [stuff][13] on that front, such as a tutorial for beginners, and some of that has migrated into the docs.
|
||||||
|
|
||||||
|
There’s a lot out there, but it’s not collated centrally, or linked from our docs as "START HERE." I should also add that I might not have the best view of this issue anymore because I haven’t actively gone looking for this information, so maybe I just never found it because I don’t need it. I don’t know that it exists. (This topic actually [came up recently][14] on the mailing list.)
|
||||||
|
|
||||||
|
The place we do point people to is: Go look at the gallery and click on the thumbnail that looks closest to what you want to do.
|
||||||
|
|
||||||
|
Ben Root presented an [Anatomy of Matplotlib tutorial][15] at SciPy several times. There’s a number of Matplotlib books that exist. It’s mixed whether the authors were contributors [to the project]. Ben Root recently wrote one about [interactive figures][16]. I’ve been approached and have turned this task down a couple of times, just because I don’t have time to write a book. So my thought for getting a technical writer was to get a technical writer to write the book, and instead of publishing the result as a book, put it in the online docs.
|
||||||
|
|
||||||
|
**GH:** Is there anyone in the Matplotlib contributor community who specializes in the documentation part of things, or takes a lot of ownership around documentation?
|
||||||
|
|
||||||
|
Nelle was doing this for Matplotlib for a bit but has stepped back. Chris Holdgraf is taking the lead on some doc-related things now. Nicholas Rougier has written a number of [extremely good tutorials][17] outside of the project's documentation.
|
||||||
|
|
||||||
|
I mean, no one uses _just_ Matplotlib. You don’t use us but not use SciPy, NumPy, or pandas. You have to be using something else to do the actual work that you now need to visualize. There are many "clean" introductions to Matplotlib in other places. For example, both Jake VanderPlas’s [analysis book][18] and Katy Huff and Anthony Scopatz’s [book][19] have introductions to Matplotlib that cover this topic to the degree they felt was needed for their purposes.
|
||||||
|
|
||||||
|
**GH:** I’d love to hear your thoughts on the role of Stack Overflow in all of this.
|
||||||
|
|
||||||
|
**TC:** That actually is how I got into the project. My Stack Overflow number is large, and it’s almost all Matplotlib questions. And how I got started is that I answered questions. A lot of the questions on Stack Overflow are, "Please read the docs for me." Which, fine. But actually, a great way to learn the library is to answer questions on Stack Overflow, because people who have problems that you don’t personally have will ask, "How do I do this?" and now you have to go figure out how to do it. It’s kind of fun.
|
||||||
|
|
||||||
|
But sometimes people ask questions and they’ve actually found a bug. And in determining that they’ve actually found a bug, I tried to figure out how to fix the bugs. So, I started some reports, which led to, "Here’s a pull request to fix the bug I found." And then when I started entering a lot of PRs, they were like, "You need to start reviewing them now," so they gave me commit rights and made me review things. And then they put me in charge.
|
||||||
|
|
||||||
|
I do like Stack Overflow. I think that to a large extent, what it replaced is the mailing list. If I have any criticism of Stack Overflow, I think it’s convincing people who are answering questions to upstream more of the results.
|
||||||
|
|
||||||
|
There are some good examples on Stack Overflow. Here’s a complex one: You have to touch these seven different functions, each of which are relatively well documented, but you have to put them together in just the right way. Some of those answers should probably go in the gallery with our annotations about how they work. Basically, if you go through Joe Kington’s top 50 answers, they should probably all go in the docs.
|
||||||
|
|
||||||
|
In other cases, the question is asked because the docstring is not clear. We need to convince people who are answering those questions to use those moments as a survey of where our documentation is not clear, instead of just answering [on Stack Overflow], and then move those answers back [to the docs].
|
||||||
|
|
||||||
|
**GH:** What’s it like managing PRs for documentation as opposed to patches and bug fixes?
|
||||||
|
|
||||||
|
**TC:** We’ve tried to streamline how we do documentation PRs. Writing documentation PRs is the most painful thing ever in open source because you get copyediting via pull request. You get picky proofreading and copyediting via GitHub comments. Like, "there’s a missing comma," or "two spaces!" And again, I keep using myself as a weird outlier benchmark, _I_ get disheartened when I write doc pull requests and then I get 50 comments regarding picky little things.
|
||||||
|
|
||||||
|
What I’ve started trying to push as the threshold on docs is, "Did [the change] make it worse?" If it didn’t make it worse, merge the change. Frequently, it takes more time to leave a GitHub comment than to fix the problem.
|
||||||
|
|
||||||
|
> "If you can use Matplotlib, you are qualified to contribute to it."
|
||||||
|
> — Tom Caswell, Matplotlib lead developer
|
||||||
|
|
||||||
|
**GH:** What’s one action you’d like members of the community who are reading this interview to take? What is one way they could make a difference on this issue?
|
||||||
|
|
||||||
|
**TC:** One thing I’d like to see more of—and I acknowledge that how to contribute to open source is a big hurdle to get over—I’ve said previously that if you can use Matplotlib, you are qualified to contribute to it. That’s a message I would like to get out more broadly.
|
||||||
|
|
||||||
|
If you’re a user and you read the docstring to something and it doesn’t make sense, and then you play around a bit and you understand that function well enough to use it—you could then start clarifying docstrings.
|
||||||
|
|
||||||
|
Because one of the things I have the hardest time with is that I personally am bad at putting myself in other people’s shoes when writing docs. I don’t know from a user’s point of view—and this sounds obnoxious but I’m deep enough in the code—what they know coming into the library as a new person. I don’t know the right things to tell them in the docstring that will actually help them. I can try to guess and I’ll probably write too much, or the wrong things. Or worse, I’ll write a bunch of stuff that refers to things they don’t know about, and now I’ve just made the function more confusing.
|
||||||
|
|
||||||
|
Whereas a user who has just encountered this function for the first time, and sorted out how to make it do what they need it to do for their purposes, is in the right mindset to write what they wish the docs had said that would have saved them an hour.
|
||||||
|
|
||||||
|
**GH:** That’s a great message, I think. Thanks for talking with me, Tom!
|
||||||
|
|
||||||
|
**TC:** You’re welcome. Thank you.
|
||||||
|
|
||||||
|
_This article was originally published on the [NumFOCUS blog][20] in 2017 and is just as relevant today. It’s republished with permission by the original interviewer and has been lightly edited for style, length, and clarity. If you want to support NumFOCUS in person, attend one of the local [PyData events][21] happening around the world. Learn more about NumFOCUS on our website: [numfocus.org][22]_
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
via: https://opensource.com/article/19/11/documentation-challenges-tom-caswell-matplotlib
|
||||||
|
|
||||||
|
作者：[Gina Helfrich, Ph.D.][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/ginahelfrich
|
||||||
|
[b]: https://github.com/lujun9972
|
||||||
|
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/files_documents_paper_folder.png?itok=eIJWac15 (Files in a folder)
|
||||||
|
[2]: https://matplotlib.org
|
||||||
|
[3]: https://twitter.com/tacaswell
|
||||||
|
[4]: https://numfocus.org/sponsored-projects
|
||||||
|
[5]: https://snarky.ca/why-i-took-october-off-from-oss-volunteering/
|
||||||
|
[6]: https://twitter.com/wesmckinn/status/909772652532953088
|
||||||
|
[7]: https://www.redhat.com/sysadmin/poor-documentation
|
||||||
|
[8]: https://twitter.com/nvaroqua
|
||||||
|
[9]: https://twitter.com/choldgraf
|
||||||
|
[10]: https://www.numfocus.org/blog/numfocus-projects-participate-in-docathon-2017/
|
||||||
|
[11]: https://twitter.com/NPRougier
|
||||||
|
[12]: https://github.com/rougier/matplotlib-tutorial
|
||||||
|
[13]: http://www.labri.fr/perso/nrougier/teaching/matplotlib/matplotlib.html
|
||||||
|
[14]: https://mail.python.org/pipermail/matplotlib-users/2017-September/001031.html
|
||||||
|
[15]: https://github.com/matplotlib/AnatomyOfMatplotlib
|
||||||
|
[16]: https://www.amazon.com/Interactive-Applications-using-Matplotlib-Benjamin/dp/1783988843
|
||||||
|
[17]: http://www.labri.fr/perso/nrougier/teaching/
|
||||||
|
[18]: http://shop.oreilly.com/product/0636920034919.do
|
||||||
|
[19]: http://shop.oreilly.com/product/0636920033424.do
|
||||||
|
[20]: https://numfocus.org/blog/matplotlib-lead-developer-explains-why-he-cant-fix-the-docs-but-you-can
|
||||||
|
[21]: https://pydata.org/
|
||||||
|
[22]: https://numfocus.org
|
||||||
@ -0,0 +1,100 @@
|
|||||||
|
[#]: collector: (lujun9972)
|
||||||
|
[#]: translator: ( )
|
||||||
|
[#]: reviewer: ( )
|
||||||
|
[#]: publisher: ( )
|
||||||
|
[#]: url: ( )
|
||||||
|
[#]: subject: (Open by nature: What building a platform for activists taught me about playful development)
|
||||||
|
[#]: via: (https://opensource.com/open-organization/19/11/open-by-nature)
|
||||||
|
[#]: author: (Laura Hilliger https://opensource.com/users/laurahilliger)
|
||||||
|
|
||||||
|
Open by nature: What building a platform for activists taught me about playful development
|
||||||
|
======
|
||||||
|
Building a global platform for environmental activists revealed a spirit
|
||||||
|
of openness that's central to human nature—and taught me how to design
|
||||||
|
for it.
|
||||||
|
![The Open Organization at Greenpeace][1]
|
||||||
|
|
||||||
|
"Open" isn't just a way we can build software. It's an attitude we can adopt toward anything we do.
|
||||||
|
|
||||||
|
And when we adopt it, we can move mountains.
|
||||||
|
|
||||||
|
Participating in a design sprint with colleagues at Greenpeace reminded me of that. As I explained in the first [two][2] [parts][3] of this [series][4], learning to think, plan, and work the open way is helping us build something truly great—a new, global platform for engaging activists who want to take action on behalf of our planet.
|
||||||
|
|
||||||
|
The sprint experience (part of a collaboration with Red Hat) reinforced several lessons about openness I've learned throughout my career as an advocate for open source, an architect of change, and a community organizer.
|
||||||
|
|
||||||
|
It also taught me a few new ones.
|
||||||
|
|
||||||
|
### An open nature
|
||||||
|
|
||||||
|
The design sprint experience reminded me just how central "openness" is to human nature. We all cook, sew, construct, write, play music, tinker, paint, tell stories—engage in the world through the creation of thousands of artifacts that allow others to understand our outlooks and worldviews. We express ourselves through our creations. We always have.
|
||||||
|
|
||||||
|
We express ourselves through our creations. We always have.
|
||||||
|
|
||||||
|
And throughout all of our expressive making, we reflect on and _share_ what we've created. We ask for feedback: _"Do you like my new recipe?" "What do you think of my painting?"_
|
||||||
|
|
||||||
|
We learn. Through trial and error (and ever-important failure), we learn what to do and what _not_ to do. Learning to make something work involves discovery and wonder in a spiral of [intrinsic motivation][5]; each new understanding unlocks new questions. We improve our skills as we create, and when we share.
|
||||||
|
|
||||||
|
I noticed something critically important while our teams were collaborating: learning to work openly can liberate a certain playfulness that often gets ignored (or buried) in many organizations today—and that playfulness can help us solve complex problems. When we're having fun learning, creating, and sharing, we're often in a flow, truly interested in our work, creating environments that others want to join. Openness can be a fount of innovation.
|
||||||
|
|
||||||
|
While our mission is a serious one, the more joy we find in it, the more people we'll attract to it. Discovery is a delightful process, and agency is empowering. The design sprint allowed us to finish with something that spurred reflection of our project—and do so with both humor and passion. The sprint left a lot of room for play, connection between participants, collaboration to solve problems, and decision-making.
|
||||||
|
|
||||||
|
### Positively open
|
||||||
|
|
||||||
|
Watching Red Hatters and Greenpeacers interact—many just having met one another for the first time—also crystallized for me some important impressions of open leadership.
|
||||||
|
|
||||||
|
Open leadership took many forms throughout the sprint. The Red Hat team showed open leadership when they adapted the agenda on the first day. Greenpeace was further ahead than other groups they'd planned for, so their plan wouldn't work. Greenpeacers were transparent about certain internal politics (because it's no use planning something that's impossible to build).
|
||||||
|
|
||||||
|
Open leaders are beacons of positivity. They assume best intentions in others. They truly listen. They live open principles. They build people up.
|
||||||
|
|
||||||
|
People left their baggage at the door. We showed up, all of us, and were present together.
|
||||||
|
|
||||||
|
Open leaders are beacons of positivity. They assume best intentions in others. They truly listen. They live open principles. They build people up. They remember to move as a collective, to ask for the insight of the collective, to thank the collective.
|
||||||
|
|
||||||
|
And in the spirit of positive, open leadership, I want to offer my own thanks.
|
||||||
|
|
||||||
|
Thanks to the Planet 4 team, a small group of people who kept pushing forward, despite the difficulties of a global project like this—a group that fought, made mistakes, and kept going despite them. They continue to pull together, and behind the scenes they're trying to be more open as they inspire the entire organization on an open journey with them (and build a piece of software at the same time!).
|
||||||
|
|
||||||
|
Thanks to the others at Greenpeace who have supported this work and those who have participated in it. Thanks to the leaders in other departments, who saw the potential of this work and helped us socialize it.
|
||||||
|
|
||||||
|
Thanks, too, to [the open organization community at Opensource.com][6] and [long-time colleagues][7] who modeled the behaviours and lent their open spirit to helping the Planet 4 team get started.
|
||||||
|
|
||||||
|
### Open returns
|
||||||
|
|
||||||
|
If openness is a way of being, then central to that way of being is [a spirit of reciprocity and exchange][8].
|
||||||
|
|
||||||
|
We belong to our communities and thus we contribute to them. We strive to be transparent so that our communities can grow and welcome new collaborators. When we infuse positivity into the world and into our projects, we create an atmosphere that invites innovation.
|
||||||
|
|
||||||
|
Our success in open source means working to nurture those ecosystems of passionate contributors. Our success as a species demands the same kind of care for our natural ecosystems, too.
|
||||||
|
|
||||||
|
Both Red Hat and Greenpeace understand the importance of ecosystems—and that shared understanding powered our collaboration on Planet 4.
|
||||||
|
|
||||||
|
As an open source software company, Red Hat both benefits from and contributes to open source software communities across the world—communities forming a technological ecosystem of passionate contributors that must always be in delicate balance. Greenpeace is also focused on the importance of maintaining ecosystems—the natural ecosystems of which we are all, irrevocably, a part. Our success in open source means working to nurture those ecosystems of passionate contributors. Our success as a species demands the same kind of care for our natural ecosystems, too, and Planet 4 is a platform that helps everyone do exactly that. For both organizations, innovation is _social_ innovation; what we create _with_ others ultimately _benefits_ others, enhancing their lives.
|
||||||
|
|
||||||
|
_Listen to Alexandra Machado of Red Hat explain social innovation._
|
||||||
|
|
||||||
|
So, really, the end of this story is just the beginning of so many others that will spawn from Planet 4.
|
||||||
|
|
||||||
|
Yours can begin immediately. [Join the Planet 4 project][9] and advocate for a greener, more peaceful future—the open way.
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
via: https://opensource.com/open-organization/19/11/open-by-nature
|
||||||
|
|
||||||
|
作者：[Laura Hilliger][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/laurahilliger
|
||||||
|
[b]: https://github.com/lujun9972
|
||||||
|
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/images/open-org/open-org-greenpeace-article-3-blog-thumbnail-500x283.png?itok=aK5TOqSS
|
||||||
|
[2]: https://opensource.com/open-organization/19/10/open-platform-greenpeace
|
||||||
|
[3]: https://opensource.com/open-organization/19/10/collaboration-breakthrough-greenpeace
|
||||||
|
[4]: https://opensource.com/tags/open-organization-greenpeace
|
||||||
|
[5]: http://en.wikipedia.org/wiki/Motivation#Intrinsic_and_extrinsic_motivation
|
||||||
|
[6]: https://opensource.com/open-organization/resources/meet-ambassadors
|
||||||
|
[7]: https://medium.com/planet4/how-to-prepare-for-planet-4-user-interviews-a3a8cd627fe
|
||||||
|
[8]: https://opensource.com/open-organization/19/9/peanuts-community-reciprocity
|
||||||
|
[9]: https://planet4.greenpeace.org/create/contribute/
|
||||||
Loading…
Reference in New Issue
Block a user