Language Selection

English French German Italian Portuguese Spanish

Why diagrams are critical to your open source project documentation

Filed under
OSS

If you've ever visited a project on GitHub (for instance) with the intention of understanding how it fits into a larger system, you'll recognise the sigh of relief you experience when you find a diagram or two on (or easily reached from) the initial landing page. This is an article about the importance of architecture and specifically about the importance of diagrams.

I'm a strong open source advocate, but source code isn't enough to make a successful project, or even, I would add, to be a truly open source project: Your documentation should not just be available to everybody, but accessible to everyone. If you want to get people involved, providing a way in is vital.

Read more

More in Tux Machines

Linux Devices and Open Hardware

  • Mini-PC and SBC build on Whiskey Lake

    Supermicro’s 3.5-inch “X11SWN-H-WOHS” SBC and “SYS-E100-9W-H” mini-PC based it feature an 8th Gen UE-series CPU, HDMI and DP, 4x USB 3.1 Gen2, 2x GbE, and 3x M.2. Supermicro has launched a fanless, 8th Gen Whiskey Lake SBC and mini-PC. The SYS-E100-9W-H mini-PC (or SuperServer E100-9W-H), which was reported on by Fanless Tech, is certified only to run Windows 10, but the 3.5-inch X11SWN-H-WOHS SBC supports Ubuntu. Applications include industrial automation, retail, smart medical expert systems, kiosks, interactive info systems, and digital signage.

  • Exor nanoSOM nS02 System-on-Module Features the 800MHz version of STM32MP1 Processor

    Exor provides a Linux RT board support package (BSP) or Android BSP for the module which also fully supports the company’s X Platform including Exor Embedded Open HMI software, Corvina Cloud IIoT platform, and IEC61131 CODESYS or Exor xPLC runtime.

  • Onyx Boox Poke2 Color eReader Launched for $299

    Manga and comics fans, rejoice! After years of getting black & white eReaders, the first commercial color eReaders are coming to market starting with Onyx Boox Poke2 Color eReader sold for $299 (but sadly sold out at the time of writing). The eReader comes with a 6-inch, 1448 x 1072 E-Ink display that supports up to 4096 colors, and runs Android 9.0 on an octa-core processor coupled with 2GB RAM and 32GB storage.

  • xDrill Smart Power Drill Supports Intelligent Speed/Torque, Laser Measuring, Digital Leveling (Crowdfunding)

    Many home appliances now have smart functions, and in my cases, I fail to see the added value, and I’m not sure why I’d want/need a connected refrigerator with a touchscreen display. So when I first saw somebody make a “smart” power drill with a small touchscreen display I laughed. But after having a closer look, Robbox xDrill smart power drill could actually be a very useful device saving you time and helping work better.

  • Raspberry Pi calls out your custom workout routine
  • Odyssey Blue: A powerful x86 and Arduino machine that supports Windows 10 and Linux

    It has been a few months since we reported on the Odyssey, a single-board computer (SBC) designed by Seeedstudio. Unlike many SBCs, the Odyssey, or ODYSSEY-X86J4105800 to give it its full name, supported the x86 instruction set. While the Odyssey can run Windows 10, it is also compatible with the Arduino ecosystem. Now, Seeedstudio has expanded on the design of the Odyssey with the Odyssey Blue.

  • Bring two analog meters out of retirement to display temperature and humidity

    Tom of Build Comics created a unique analog weather station that shows temperature and humidity on a pair of recycled gauges. An Arduino Nano reads the levels using a DHT22 sensor and outputs them in the proper format for each display. Both units have a new printed paper backing to indicate conditions, along with a trimmer pot for calibration. To set the build off nicely, the Nano and other electronics are housed inside a beautiful custom wooden box, to which the antique meters are also affixed.

Programming Leftovers

  • Engineer Your Own Electronics With PCB Design Software

    A lot of self-styled geeks out there tend to like to customize their own programs, devices, and electronics. And for the true purists, that can mean building from the ground up (you know, like Superman actor Henry Cavill building a gaming PC to the delight of the entire internet). Building electronics from the ground up can mean a lot of different things: acquiring parts, sometimes from strange sources; a bit of elbow grease on the mechanical side of things; and today, even taking advantage of the 3D printing revolution that’s finally enabling people to manufacture customized objects in their home. Beyond all of these things though, engineering your own devices can also mean designing the underlying electronics — beginning with printed circuit boards, also known as PCBs. [...] On the other hand, there are also plenty of just-for-fun options to consider. For example, consider our past buyer’s guide to the best Linux laptop, in which we noted that you can always further customize your hardware. With knowledge of PCB design, that ability to customize even a great computer or computer setup is further enhanced. You might, for instance, learn how to craft PCBs and devices amounting to your own mouse, gaming keyboard, or homemade speakers — all of which can make your hardware more uniquely your own. All in all, PCB design is a very handy skill to have in 2020. It’s not typically necessary, in that there’s usually a device or some light customization that can give you whatever you want or need out of your electronics. But for “geeks” and tech enthusiasts, knowledge of PCB design adds another layer to the potential to customize hardware.

  • Programming pioneer Fran Allen dies aged 88 after a career of immense contributions to compilers

    Frances Allen, one of the leading computer scientists of her generation and a pioneer of women in tech, died last Tuesday, her 88th birthday. Allen is best known for her work on compiler organisation and optimisation algorithms. Together with renowned computer scientist John Cocke, she published a series of landmark papers in the late '60s and '70s that helped to lay the groundwork for modern programming. In recognition of her efforts, in 2006 Allen became the first woman to be awarded the AM Turing Award, often called the Nobel Prize of computing.

  • Excellent Free Tutorials to Learn ECMAScript

    ECMAScript is an object‑oriented programming language for performing computations and manipulating computational objects within a host environment. The language was originally designed as a scripting language, but is now often used as a general purpose programming language. ECMAScript is best known as the language embedded in web browsers but has also been widely adopted for server and embedded applications.

  • Alexander Larsson: Compatibility in a sandboxed world

    Compatibility has always been a complex problems in the Linux world. With the advent of containers/sandboxing it has become even more complicated. Containers help solve compatibility problems, but there are still remaining issues. Especially on the Linux desktop where things are highly interconnected. In fact, containers even create some problems that we didn’t use to have. Today I’ll take a look at the issues in more details and give some ideas on how to best think of compatibility in this post-container world, focusing on desktop use with technologies like flatpak and snap. [...] Another type of compatibility is that of communication protocols. Two programs that talk to each other using a networking API (which could be on two different machines, or locally on the same machine) need to use a protocol to understand each other. Changes to this protocol need to be carefully considered to ensure they are compatible. In the remote case this is pretty obvious, as it is very hard to control what software two different machines use. However, even for local communication between processes care has to be taken. For example, a local service could be using a protocol that has several implementations and they all need to stay compatible. Sometimes local services are split into a service and a library and the compatibility guarantees are defined by the library rather than the service. Then we can achieve some level of compatibility by ensuring the library and the service are updated in lock-step. For example a distribution could ship them in the same package.

  • GXml-0.20 Released

    GXml is an Object Oriented implementation of DOM version 4, using GObject classes and written in Vala. Has a fast and robust serialization implementation from GObject to XML and back, with a high degree of control. After serialization, provides a set of collections where you can get access to child nodes, using lists or hash tables. New 0.20 release is the first step toward 1.0. It provides cleaner API and removes old unmaintained implementations. GXml is the base of other projects depending on DOM4, like GSVG an engine to read SVG documents based on its specificacion 1.0. GXml uses a method to set properties and fill declared containers for child nodes, accessing GObject internals directly, making it fast. A libxml-2.0 engine is used to read sequentially each node, but is prepared to implement new ones in the future.

  • Let Mom Help You With Object-Oriented Programming

    Mom is a shortcut for creating Moo classes (and roles). It allows you to define a Moo class with the brevity of Class::Tiny. (In fact, Mom is even briefer.) A simple example: Mom allows you to use Moo features beyond simply declaring Class::Tiny-like attributes though. You can choose whether attributes are read-only, read-write, or read-write-private, whether they're required or optional, specify type constraints, defaults, etc.

  • Perl Weekly Challenge 73: Min Sliding Window and Smallest Neighbor

    These are some answers to the Week 73 of the Perl Weekly Challenge organized by Mohammad S. Anwar. Spoiler Alert: This weekly challenge deadline is due in a few days from now (on Aug. 16, 2020). This blog post offers some solutions to this challenge, please don’t read on if you intend to complete the challenge on your own.

  • [rakulang] 2020.32 Survey, Please

    The TPF Marketing Committee wants to learn more about how you perceive “The Perl Foundation” itself, and asks you to fill in this survey (/r/rakulang, /r/perl comments). Thank you!

Hardware With Linux Support: NUVIA and AMD Wraith Prism

  • Performance Delivered a New Way

    The server CPU has evolved at an incredible pace over the last two decades. Gone are the days of discrete CPUs, northbridges, southbridges, memory controllers, other external I/O and security chips. In today’s modern data center, the SoC (System On A Chip) does it all. It is the central point of coordination for virtually all workloads and the main hub where all the fixed-function accelerators connect, such as AI accelerators, GPUs, network interface controllers, storage devices, etc.

  • NUVIA Published New Details On Their Phoenix CPU, Talks Up Big Performance/Perf-Per-Watt

    Since leaving stealth last year and hiring some prominent Linux/open-source veterans to complement their ARM processor design experts, we have been quite eager to hear more about this latest start-up aiming to deliver compelling ARM server products. Today they shared some early details on their initial "Phoenix" processor that is coming within their "Orion" SoC. The first-generation Phoenix CPU is said to have a "complete overhaul" of the CPU pipeline and is a custom core based on the ARM architecture. They believe that Phoenix+Orion will be able to take on Intel/AMD x86_64 CPUs not only in raw performance but also in performance-per-Watt.

  • Take control of your AMD Wraith Prism RGB on Linux with Wraith Master

    Where the official vendor doesn't bother with supporting Linux properly, once again the community steps in to provide. If you want to tweak your AMD Wraith Prism lighting on Linux, check out Wraith Master. It's a similar project to CM-RGB that we previously highlighted. With the Wraith Master project, they provide a "feature-complete" UI and command-line app for controlling the fancy LED system on AMD's Wraith Prism cooler with eventual plans to support more.

The Massive Privacy Loopholes in School Laptops

It’s back to school time and with so many school districts participating in distance learning, many if not most are relying on computers and technology more than ever before. Wealthier school districts are providing their students with laptops or tablets, but not all schools can afford to provide each student with a computer which means that this summer parents are scrambling to find a device for their child to use for school. Geoffery Fowler wrote a guide in the Washington Post recently to aid parents in sourcing a computer or tablet for school. Given how rough kids can be with their things, many people are unlikely to give their child an expensive, premium laptop. The guide mostly focuses on incredibly low-cost, almost-disposable computers, so you won’t find a computer in the list that has what I consider a critical feature for privacy in the age of video conferencing: hardware kill switches. Often a guide like this would center on Chromebooks as Google has invested a lot of resources to get low-cost Chromebooks into schools yet I found Mr. Fowler’s guide particularly interesting because of his opinion on Chromebooks in education... Read more Also: Enabling Dark Mode on a Chromebook (Do not try this at home)