Posts

documentation

At the upcoming APIStrat conference in Portland, Taylor Barnett will explore various documentation design principles and discuss best practices.

Taylor Barnett, a Community Engineer at Keen IO, says practice and constant iteration are key to writing good documentation.  At the upcoming API Strategy & Practice Conference 2017, Oct. 31 -Nov. 2 in Portland, OR, Barnett will explain the different types of docs and describe some best practices.

In her talk — Things I Wish People Told Me About Writing Docs — Barnett will look at how people consume documentation and discuss tools and tactics to enable other team members to write documentation.  Barnett explains more in this edited interview.

The Linux Foundation: What led you to this talk? Have you encountered projects with bad documentation?

Taylor Barnett: For the last year, my teammate, Maggie Jan, and I have been leading work to improve the developer content and documentation experience at Keen IO. It’s no secret that developers love excellent documentation, but many API companies aren’t always equipped with the resources to make that happen. As a result of this, we all come across a lot of bad documentation when you are trying to use developer tools and APIs.

The Linux Foundation: Often, there is a team of documentation writers and there are developers who wrote that piece of software; both are experts in their own fields, but they need a lot of collaboration to create usable docs. How can that collaboration be improved?

Barnett: In large companies, this can definitely be true, although in many companies documentation is still owned by various teams. The need for more collaboration still applies, though. One way to improve collaboration is bringing docs into the product development process early on. If you wait until everything is done and going to be released soon, people writing documentation are going to feel left out of the process and like an afterthought. If people working on the product development collaborate early on, not only does the product become better, but so does the documentation. People who are writing documentation usually spend some time figuring out the API or tool they are writing about, so they only get better when they can work with the people doing product development early on. Also, they can give great feedback from a user’s perspective much earlier in the process.

Another way to improve collaboration is to bring more people into the documentation review process. We do most of our documentation reviews in GitHub. It’s great to not only have someone in the role of an editor review it but also people from the Engineering or Product teams. It increases the number of eyes on the docs and helps make them better.

The Linux Foundation: How should developers approach documentation?

Barnett: Most developers are pretty familiar with the idea of Test Driven Development (TDD), but how familiar are they with Documentation Driven Development (DDD)? The flow for DDD is:

  1. Write or update documentation,
  2. Get feedback on that documentation,
  3. Write a failing test according to that documentation (TDD),
  4. Write code to pass the failing test,
  5. Repeat.

It can be an excellent way for developers to save a lot of time and prevent spending too much time on poorly designed features. As Isaac Schlueter, co-founder of npm, says about Documentation Driven Development, writing clear prose is an “effective way to increase productivity by reducing both the frequency and cost of mistakes.” Our brains can only hold so much information at once. In computer terms, our working memory size is pretty small. Writing down some of the information we are thinking about is a way to “off-load significant chunks of thought with hardly any data-loss,” while allowing us to think slower and more carefully.

For example: At Keen IO, we recently split our JavaScript library into three different modules. This decision was inspired by the documentation we were maintaining. We had tried to streamline the docs, but there was just too much to cover in an attention-constrained world. Many important details and features were hidden in the noise. For example, if all of the documentation was written sooner, we may have made this decision sooner.

Also, as a developer who is writing docs myself, constant iteration and practice are important. Your first version of the docs aren’t going to be great, but with focusing on trying to write clear prose, they will get better with time. Also, having another person who is not familiar with the product and can step through the documentation to review it is essential.

The Linux Foundation: If developers are writing documentation for other developers, how can they really think as the users?

Barnett: I used to think that developers are the best people to write docs for other developers because they are one of them. While I still believe this is partially true, some developers also assume a lot of knowledge. If it has been a while since a developer has done something, the “curse of knowledge” can exist. The more you know, the more you forget what it was like before. That’s why I like to talk about empathic documentation.

You need to empathize with the user on the other end. Don’t assume they know how to do something and give resources to fill in the steps that might seem “easy” to you. Also, hearing that something is “easy” or “simple” when something is not working on the user’s’ end is the worst feeling. It makes your users doubt themselves, feel frustrated, and a bunch of other negative emotions. Always try to remember you need to be empathetic!

The Linux Foundation: What’s the importance of tools in creating documentation?

Barnett: Very important! Earlier I mentioned using GitHub for reviews. I also would recommend having some continuous integration testing in place for your documentation site if you aren’t using a service like ReadMe or Apiary to make sure you don’t break it. A related topic is, do you build your own thing or use a service? Tools can be helpful, but they might not always be the best fit. You have to find a balance based on your current resources. Lastly, I would recommend checking out Anne Gentle’s book, Docs Like Code. She brings up tools a lot in the book.

The Linux Foundation: Who should attend your session?

Barnett: Everyone! Just kidding (kind of). If you are in any role that is developer facing like developer relations, evangelists, advocates, marketers, etc., if you are on a Product team for a developer focused product or platform, or if you are a developer or engineer who wants to write better docs.

The Linux Foundation: What is the main takeaway from your talk?

Barnett: Anyone can write docs, but with some practice, iteration, and working on different documentation writing skills anyone can write better docs.

Learn more in Taylor Barnett’s talk at the APIStrat conference coming up Oct. 31 – Nov. 2 in Portland, Oregon.

MesosCon

Sign up for free live video streaming of all keynote sessions at MesosCon Europe.

Can’t make it to MesosCon Europe in Prague this week? The Linux Foundation is pleased to offer free live video streaming of all keynote sessions on Thursday, Oct 26 and Friday, Oct 27, 2017.

MesosCon is an annual conference organized by the Apache Mesos community, bringing together users and developers to share and learn about the project and its growing ecosystem. Users, developers, experts, and community members will convene next week.

Apache Software Foundation, Mesosphere, and Netflix are among the many organizations that will keynote next week.

The livestream will begin on Thursday, Oct. 26 at 9 a.m. CEST (Central European Summer Time). Sign up now! You can also follow our live event updates on Twitter with #MesosCon.

All keynotes will be broadcasted live, including a welcome and opening remarks by Ben Hindman, Co-Creator, Apache Mesos and Founder, Mesosphere.

Other featured keynotes include:

  • Rich Bowen, VP Conferences, Apache Software Foundation will analyze The Apache Way.
  • Katharina Probst, Netflix will talk about making and keeping Netflix highly available.
  • SMACK in the enterprise panel.
  • Pierre Cheynier, Operations Engineer, Criteo will discuss operating 600+ Mesos servers on 7 data centers.
  • And more.

View the full schedule of keynotes.

Sign up now for the free live video stream.

Once you sign up, you’ll be able to view the livestream on the same page. If you sign up prior to the livestream day/time, simply return to this page and you’ll be able to view.

 

Open Source Summit livestream

The Linux Foundation is pleased to offer free live video streaming of all keynote sessions at Open Source Summit and Embedded Linux Conference Europe, Oct. 23 to Oct. 25, 2017.

Join 2000 technologists and community members next week as they convene at Open Source Summit Europe and Embedded Linux Conference Europe in Prague. If you can’t be there in person, you can still take part, as The Linux Foundation is pleased to offer free live video streaming of all keynote sessions on Monday, Oct. 23 through Wednesday, Oct. 25, 2017.  So, you can watch the event keynotes presented by Google, Intel, and VMware, among others.

The livestream will begin on Monday, Oct. 23 at 9 a.m. CEST (Central European Summer Time). Sign up now! You can also follow our live event updates on Twitter with #OSSummit.

All keynotes will be broadcasted live, including talks by Keila Banks, 15-year-old Programmer, Web Designer, and Technologist with her father Philip Banks; Mitchell Hashimoto, Founder, HashiCorp Founder of HashiCorp and Creator of Vagrant, Packer, Serf, Consul, Terraform, Vault and Nomad; Jan Kizska, Senior Key Expert, Siemens AG; Dirk Hohndel, VP & Chief Open Source Officer, VMware in a Conversation with Linux and Git Creator Linus Torvalds; Michael Dolan, Vice President of Strategic Programs & The Linux Foundation; and Jono Bacon, Community/Developer Strategy Consultant and Author.

Other featured conference keynotes include:

  • Neha Narkhede — Co-Founder & CTO of Confluent will discuss Apache Kafka and the Rise of the Streaming Platform
  • Reuben Paul — 11-year-old Hacker, CyberShaolin Founder and cybersecurity ambassador will talk about how Hacking is Child’s Play
  • Arpit Joshipura — General Manager, Networking, The Linux Foundation who will discuss Open Source Networking and a Vision of Fully Automated Networks
  • Imad Sousou — Vice President and General Manager, Software & Services Group, Intel
  • Sarah Novotny — Head of Open Source Strategy for GCP, Google
  • And more

View the full schedule of keynotes.

And sign up now for the free live video stream.

Once you sign up to watch the event keynotes, you’ll be able to view the livestream on the same page. If you sign up prior to the livestream day/time, simply return to this page and you’ll be able to view.

One of my primary goals at The Linux Foundation is to foster innovation across the entire open source networking ecosystem. This involves coordinating across multiple open source projects and initiatives and identifying key areas for collaboration to create an open source networking stack.

We are working across the entire ecosystem with industry-leading partners — from developers to service providers to vendors — to unify various open source components and create solutions that will accelerate network transformation. As part of this journey, I am pleased to introduce Open Source Networking Days (OSN Days), a series of free events that are hosted and organized by local user groups and The Linux Foundation members, with support from our projects, including DPDK, FD.io, ONAP, OpenDaylight, OPNFV, PNDA, and others.

OSN Days are a fantastic opportunity for network developers and users to learn how ONAP, OPNFV, OpenDaylight  and other open source initiatives are changing NFV/SDN orchestration and networking solutions. Stops on the tour include: Paris, Milan, Stockholm, London, Tel Aviv, and Japan. Register today for an upcoming OSN Day in your region.

The day-long events will start with a plenary session where attendees will hear from site hosts and The Linux Foundation speakers on the state of the industry and the collaboration and touch points between projects that make up the open source networking stack. Presenters will also explore how business opportunities like 5G and IoT are enabled by network transformation.  In the afternoon, events may feature technical sessions, tutorials, demonstrations, and workshops that empower attendees to participate, contribute, and deepen their knowledge of open source networking.

Our first OSN Day kicks off October 9 in Paris, followed by stops in Milan (October 12), Stockholm (October 13), London (October 16), Tel Aviv (October 19), and Japan (October 19). Thanks to our incredible site hosts and sponsors Amdocs, ATOS, Cloudify, Ericsson, Huawei, NEC, Orange, Red Hat, SUSE, and Vodafone, along with our high-caliber roster of speakers, for helping to make these OSN Days a reality!

More details about the events, including site-specific agendas, registration info, and details on hotel and travel, can be found here: https://sites.google.com/linuxfoundation.org/osndays/home. If you have any questions, or would like to host an event yourself in the future, please email OSNDays@linuxfoundation.org.

Open Source Summit Europe is not far away! This year’s event — held Oct. 23-26 in Prague, Czech Republic — will feature a wide array of speakers, including open source community expert Jono Bacon, 11-year-old hacker Reuben Paul, and Linux creator Linus Torvalds.

At OS Summit Europe, you will have the opportunity to collaborate, share, learn, and connect with 2,000 technologists and community members, through keynote presentations, technical talks, and many other event activities.  

Confirmed keynote speakers for OS Summit Europe include:

  • Jono Bacon, Community/Developer Strategy Consultant and Author

  • Keila Banks, 15-year-old Programmer, Web Designer and Technologist, with her father Phillip Banks

  • Mitchell Hashimoto, Founder of HashiCorp and Creator of Vagrant, Packer, Serf, Consul, Terraform, Vault, and Nomad

  • Neha Narkhede, Co-founder & CTO, Confluent

  • Sarah Novotny, Program Manager, Kubernetes Community, Google

  • Reuben Paul, 11-year-old Hacker, CyberShaolin Founder and Cyber Security Ambassador

  • Imad Sousou, VP, Software Services Group & GM, Open Source Technology Center, Intel Corporation

  • Linus Torvalds, Creator of Linux and Git in conversation with Dirk Hohndel, VP, Chief Open Source Officer, VMware

  • Jim Zemlin, Executive Director, The Linux Foundation

The full schedule will be published in the next few weeks, and applications are now being accepted for diversity and needs-based scholarships.

Registration is discounted to $800 through August 27, and academic and hobbyist rates are also available. Linux.com readers receive an additional $40 off with code LINUXRD5. Register Now!

Open Source Summit North America is less than two months away! Join 2,000+ open source professionals Sept. 11-14 in Los Angeles, CA, for exciting keynotes and technical talks covering all things Linux, cloud, containers, networking, emerging open source technologies, and more.

Register now!

With your registration, you also get access to many special events throughout the four-day conference. Special events include:

  • New Speed Networking Workshop: Looking to grow your technical skills, get more involved in an open source community, or make a job change? This networking and mentoring session taking place Monday, Sept. 11 is for you!

  • New Recruiting Program: Considering a career move or a job change? This year we are making it easier than ever for attendees to connect with companies looking for new candidates.

  • Evening Events: Join fellow attendees for conversation, collaboration and fun at numerous evening events including the attendee reception at Paramount Studios featuring studio tours, live music, and dinner from LA favorites In-N-Out, Coolhaus, Pink’s and more!

  • Women in Open Source Lunch: All women attendees are invited to connect at this networking lunch, sponsored by Intel, on Monday, Sept. 11.

  • Dan Lyons Book Signing: Attendees will have the opportunity to meet author Dan Lyons on Tuesday, Sept. 12. The first 100 attendees will receive a free signed copy of his book Disrupted: My Misadventure in the Start-Up Bubble.

  • Thursday Summits & Tutorials: Plan to stay on September 14, to attend the Diversity Empowerment Summit (Hosted by HPE & Intel), Networking Mini-Summit or deep-dive tutorials – all included in your OSS NA registration!

  • New Executive Track: Full details coming soon on this special event, hosted by IBM, taking place Tuesday, Sept. 12.

  • Morning Activities for Attendees: Morning meditation, a 5K fun run, and a downtown Los Angeles sightseeing bus tour.

Check back for updates on even more activities, including our Attendee Partner Program, Kids Day (an opportunity for kids to learn Scratch programming, in partnership with LA Makerspace), and Puppy Pawlooza (enjoy playtime with shelter dogs thanks to our partnership with LA Animal Rescue).

Linux.com readers receive an additional $47 off with code LINUXRD5. Register now »

Linux is hot right now. Everybody is looking for Linux talent. Recruiters are knocking down the doors of anybody with Linux experience, and there are tens of thousands of jobs waiting to be filled. But what if you want to take advantage of this trend and you’re new to Linux? How do you get started?

  1. Install Linux  

    It should almost go without saying, but the first key to learning Linux is to install Linux. Both the LFS101x and the LFS201 courses include detailed sections on installing and configuring Linux for the first time.

  2. Take LFS101x

    If you are completely new to Linux, the best place to start is our free LFS101x Introduction to Linux course. This online course is hosted by edX.org, and explores the various tools and techniques commonly used by Linux system administrators and end users to achieve their day-to-day work in a Linux environment. It is designed for experienced computer users who have limited or no previous exposure to Linux, whether they are working in an individual or enterprise environment. This course will give you a good working knowledge of Linux from both a graphical and command line perspective, allowing you to easily navigate through any of the major Linux distributions.

  3. Look into LFS201

    Once you’ve completed LFS101x, you’re ready to start diving into the more complicated tasks in Linux that will be required of you as a professional sysadmin. To gain those skills, you’ll want to take LFS201 Essentials of Linux System Administration. The course gives you in-depth explanations and instructions for each topic, along with plenty of exercises and labs to help you get real, hands-on experience with the subject matter.

    If you would rather have a live instructor teach you or you have an employer who is interested in helping you become a Linux sysadmin, you might also be interested in LFS220 Linux System Administration. This course includes all the same topics as the LFS201 course, but is taught by an expert instructor who can guide you through the labs and answer any questions you have on the topics covered in the course.

  4. Practice!

    Practice makes perfect, and that’s as true for Linux as it is for any musical instrument or sport. Once you’ve installed Linux, use it regularly. Perform key tasks over and over again until you can do them easily without reference material. Learn the ins and outs of the command line as well as the GUI. This practice will ensure that you’ve got the skills and knowledge to be successful as a professional Linux sysadmin.

  5. Get Certified

    After you’ve taken LFS201 or LFS220 and you’ve gotten some practice, you are now ready to get certified as a system administrator. You’ll need this certification because this is how you will prove to employers that you have the necessary skills to be a professional Linux sysadmin.

    There are several Linux certifications on the market today, and all of them have their place. However, most of these certifications are either centered on a specific distro (like Red Hat) or are purely knowledge-based and don’t demonstrate actual skill with Linux. The Linux Foundation Certified System Administrator certification is an excellent alternative for someone looking for a flexible, meaningful entry-level certification.

  6. Get Involved

    At this point you may also want to consider joining up with a local Linux Users Group (or LUG), if there’s one in your area. These groups are usually composed of people of all ages and experience levels, so regardless of where you are at with your Linux experience, you can find people with similar skill levels to bond with, or more advanced Linux users who can help answer questions and point you towards helpful resources. To find out if there’s a LUG near you, try looking on meetup.com, check with a nearby university, or just do a simple Internet search.

    There are also many online communities available to you as you learn Linux. These sites and communities provide help and support to both individuals new to Linux or experienced administrators:

7. Learn To Love The Documentation

Last but not least, if you ever get stuck on something within Linux, don’t forget about Linux’s included documentation. Using the commands man (for manual), info and help, you can find information on virtually every aspect of Linux, right from within the operating system. The usefulness of these built-in resources cannot be overstated, and you’ll find yourself using them throughout your career, so you might as well get familiar with them early on.

Interested in learning more about a career in system administration? Check out our free ebook “Future Proof Your SysAdmin Career.

The upcoming Open Source Summit NA — Sept. 11-14 in Los Angeles — offers many exciting keynote presentations and technical talks covering a wide array of topics, including cloud computing, containers, networking, diversity, and more. And, it’s also host to several co-located events that provide even more opportunities for collaboration and learning. Here are some of the events taking place.

Hacking for Humanity — A Social Innovation Hackathon with Girls in Tech

The Linux Foundation has teamed up with Girls in Tech Los Angeles for a unique two-day hackathon program to tackle global challenges. We invite women and men across all fields, including developers, designers, product developers, and entrepreneurs to participate.

Date/Time: Thursday, September 14, 10:00 am – Friday, September 15, 6:00 pm

Location: Plaza I/II, JW Marriott LA Live

Registration Cost: Complimentary. Register Here!

How to Build Habit-Forming Products Workshop

Learn how to build repeat engagement in this in-depth product development strategy workshop presented by Nir Eyal, author of Hooked: How to Build Habit-Forming Products. Eyal has constructed a practical framework and process for designing better products that gives product managers, designers, and marketers a new way for thinking of the necessary components of changing user behavior. Although no previous background is required, attendees are encouraged to come to the workshop with a product or business idea in mind.

Date: Thursday, September 14

Time: 6:30 – 9:30 pm

Location: Georgia I-II, JW Marriott LA Live

Registration Cost: $199 USD. Click here to register!

Kubernetes Core Concepts Live Training

This one-day course presented by Sebastien Goasguen serves as a crash course to learn the basics of Kubernetes. It is suitable for beginners and aimed at developers and system administrators who want to get started with Kubernetes. You will discover the Kubernetes architecture and how to install it. You will then learn how to use its basic primitives (i.e., pods, deployments and services) to build your own distributed application.

The course will be a mix of lectures, demos and hands-on exercises aimed at administrators and application developers who want to understand the overall architecture of a Kubernetes cluster and learn how to use Docker images in a Kubernetes cluster.

Date: Thursday, September 14

Time: 8:30 am – 5:00 pm

Location: Olympic 1, JW Marriott LA Live

Registration Cost: $429 USD. Pre-registration is required. Add this training to your existing Open Source Summit NA registration here.

Linux Security Summit

The Linux Security Summit (LSS) is a technical forum for collaboration between Linux developers, researchers, and end users. Its primary aim is to foster community efforts in analyzing and solving Linux security challenges.

Date: Thursday, September 14 – Friday, September 15

Time: 9:00 am – 5:00 pm (subject to change)

Location: Gold 4, JW Marriott LA Live

Registration Cost: $100 USD. You can add Linux Security Summit to your existing registration here. If you would like to attend Linux Security Summit only, please register here.

Moby Summit

The Moby Summit is a small collaborative event taking place on Thursday, September 14 alongside Open Source Summit North America. This summit is for container users who are actively maintaining, contributing or generally involved in the design and development of the Moby Project and its components: runC/ containerd, LinuxKit, Infrakit, SwarmKit, HyperKit, DataKit, VPNKit, Notary, libnetwork, etc.

Date: Thursday, September 14

Time: 8:00 am – 7:00 pm

Location: Diamond Ballroom 8/9/10, JW Marriott LA Live

Registration Cost: Purchase tickets for Moby Summit here! All revenue from ticket sales will be donated to a non-profit organization promoting diversity in the tech industry.

Open Source Entrepreneur Network Symposium

This one-day symposium is presented by John Mark Walker, Founder, Open Source Entrepreneur Network. Everyone uses open source now. It’s not so much a question of whether you use open source but how you optimize your usage and contributions. In this symposium, we will discuss the myriad of business models for selling open source-based products and services, investigate potential legal landmines around contributing to and using open source software, and look at best practices for incorporating the best of upstream open source innovation into your organization.

Date: Thursday, September 14

Time: 9:00 am – 4:00 pm

Location: Georgia I-II, JW Marriott LA Live

Registration Cost: $150 USD. Pre-registration is required. Add this symposium to your existing Open Source Summit NA registration here.

You can see the full schedule for Open Source Summit here.

Save $150 through July 30. Linux.com readers save an additional $47 with discount code LINUXRD5. Register now!

This week in open source and Linux news, Hortonworks CTO considers why open source is the new normal in analytics, new Linux Foundation edX MOOC called a “no-brainer” and more! Read on for the top headlines of the week

1) Hortonworks CTO unpacks how open source data architectures are “now considered mainstream in the IT environments and are widely deployed in live production in several industries.”

Open Source Is The New Normal In Data and Analytics – Forbes

2) Steven J. Vaughan-Nichols calls new Linux Foundation Kubernetes MOOC a “no-brainer.”

Linux Foundation Offers Free Introduction to Kubernetes Class – ZDNet

3) “Lyft’s move is part of a greater trend among tech companies to open-source their internal tools for performing machine learning work.”

Lyft to Open-Source some of its AI Algorithm Testing Tools – VentureBeat

4) The Linux Foundation has become a catalyst for the shift toward network functions virtualization (NFV) and software-defined networking (SDN)

How is The Linux Foundation Shaping Telecom? – RCRWireless News

5) You can now download a flavor of the popular Linux distribution to run inside Windows 10

Ubuntu Linux is Available in the Windows Store– engadget

In this preview of Containers for Developers and Quality Assurance (LFS254) training course from The Linux Foundation, we’ve covered Docker installation, introduced Docker Machine, performed basic Docker container and image operations, and looked at Dockerfiles and Docker Volumes.

This final article in the series looks at Docker Compose, which is a tool you can use to create multi-container applications with just one command. If you are using Docker for Mac or Windows, or you install the Docker Toolbox, then Docker Compose will be available by default. If not, you can download it manually.

To try out WordPress, for example, let’s create a folder called wordpress, and, in that folder, create a file called docker-compose.yaml. We will be exporting the wordpress container on the 8000 port of the host system.

When we start an application with Docker Compose, it creates a user-defined network on which it attaches the containers for the application. The containers communicate over that network. As we have configured Docker Machine to connect to our dockerhost, Docker Compose would also use that.

Now, with the docker-compose up command, we can deploy the application. With docker-compose ps command, we can list the containers created by Docker Compose, and with docker-compose down, we can stop and remove the containers. This also removes the network associated with the application. To additionally delete the associated volume, we need to pass the -v option with the docker-compose down command.

 Want to learn more? Access all the free sample chapter videos now!

This online course is presented almost entirely on video, and the material is prepared and presented by Neependra Khare (@neependra), Founder and Principal Consultant at CloudYuga, Docker Captain, and author of the Docker Cookbook.