Open-source News

Steam Deck hitting retail in Hong Kong, Taiwan and later Japan and ...  GamingOnLinux

Last month Qualcomm published updated patches for their Cloud AI 100 kernel driver to support this inference accelerator. The Qualcomm engineers said at the time that their user-space driver and associated compiler would be published shortly. That panned out and the user-space portion of this open-source AI inference stack was recently published...

Valheim got a big patch with performance upgrades and controller ...  GamingOnLinux

Qt 6.4.3 is out today as the newest point release to this current stable series of the Qt6 tool-kit. This release is another big one with 300+ fixes in tow...

Steam Deck and desktop Steam upgraded with LAN transfers out of ...  GamingOnLinux

NordVPN's Linux App is Now Totally Open Source  It's FOSS News

Mold 1.11 is out as the newest version of this open-source high performance linker that rivals the likes of LLVM LLD and GNU Gold for very speedy linking across multiple CPU architectures...

Amazon Linux 2023: Create and execute cloud-based applications ...  Help Net Security

3 ways to install PHPUnit in Ubuntu 22.04 or 20.04 LTS  H2S Media

9 Ubuntu 23.04 (Lunar Lobster) Features We Spotted So Far  It's FOSS News

How to install Tuxedo OS on your computer - Addictive Tips Guide  AddictiveTips

How to install Tuxedo OS on your computer  AddictiveTips

Write documentation that actually works for your community olga-merkulova Thu, 03/16/2023 - 03:00

What distinguishes successful and sustainable projects from those that disappeared into the void? Spoiler — it's community. Community is what drives an open source project, and documentation is one of the foundational blocks for building a community. In other words, documentation isn't only about documentation.

Establishing good documentation can be difficult, though. Users don't read documentation because it's inconvenient, it goes out of date very quickly, there's too much, or there's not enough.

The development team doesn't write documentation because of the "it's obvious for me, so it's obvious to everyone" trap. They don't write because they are too busy making the project exist. Things are developing too fast, or they're not developing fast enough.

But good documentation remains the best communication tool for groups and projects. This is especially true considering that projects tend to get bigger over time.

Documentation can be a single source of truth within a group or a company.  This is important when coordinating people toward a common goal and preserving knowledge as people move on to different projects.

So how do you write appropriate documentation for a project and share it with the right people?

What is successful community documentation?

To succeed in writing documentation in your community:

• Organize your routine

• Make it clear and straightforward

• Be flexible, make changes to the routine according to a specific situation

• Do version control

Image by:

(Olga Merkulova, CC BY-SA 4.0)

Being flexible doesn't mean being chaotic. Many projects have succeeded just because they are well-organized.

James Clear (author of Atomic Habits) wrote, "You do not rise to the level of your goals. You fall to the level of your systems." Be sure to organize the process so that the level is high enough to achieve success.

Design the process

Documentation is a project. Think of writing docs as writing code. In fact, documentation can be a product and a very useful one at that.

This means you can use the same processes as in software development: analysis, capturing requirements, design, implementation, and maintenance. Make documentation one of your processes.

Think about it from different perspectives while designing the process. Not all documentation is the right documentation for everyone.

Most users only need a high-level overview of a project, while API documentation is probably best reserved for developers or advanced users.

Developers need library and function documentation. Users are better served by example use cases, step-by-step guides, and an architectural overview of how a project fits in with the other software they use.

Image by:

(Olga Merkulova, CC BY-SA 4.0)

Ultimately, before creating any process, you must determine what you need:

• Focus groups: this includes developers, integrators, administrators, users, sales, operations, executives

• Level of expertise: Keep in mind the beginner, intermediate, and advanced users

• Level of detail: There's room for a high-level overview as well as technical detail, so consider how you want these to be presented

• Journeys and entry points: How do people find the documentation, how they use it

When you ponder these questions, it helps you structure information you want to communicate through documentation. It defines clear metrics on what has to be in the documentation.

Here's how to approach building a process around documentation.

Coding conventions

The code itself should make sense. Documentation should be expressed through good class names, file names, and so on. Create common coding standards and make a self-documented code process by thinking about:

• Variable naming conventions

• Make names understandable by using class, function naming schemes

• Avoid deep nesting, or don't nest at all

• Do not simply copy-and-paste code

• No long methods should be used

• Avoid using magic numbers (use const instead)

• Use extract methods, variables, and so on

• Use meaningful directory structures, modules, packages, and files

Testing along with engineering

Testing isn't only about how code should behave. It's also about how to use an API, functions, methods, and so on. Well-written tests can reveal base and edge case scenarios. There's even a test-driven development practice that focuses on creating test cases (step by step scenarios of what should be tested and how) before code development.

Version control

Version control, even for your documentation, helps you track the logic of your changes. It can help you answer why a change was made.

Make sure comments during commits explain WHY a change was made, not WHAT change was made.

The more engaging the documentation process is, the more people will get into it. Add creativity and fun to it. You should think about readability of documentation by using:

• software code conventions

• diagrams and graphs (that are also explained in text)

• mind maps

• concept maps

• infographics

• images (highlight important parts)

• short videos

By using different ways of communication, you offer more ways to engage with your documentation. This can help forestall misunderstanding (different languages, different meanings), and different learning styles.

Here are some software tools for creating documentation:

• Javadoc, Doxygen, JsDoc, and so on: Many languages have automated documentation tools to help capture major features in code
• Web hooks and CI/CD engines: Allows continuous publication of your documentation
• Restructured Text, Markdown, Asciidoc: File formats and processing engines help you produce beautiful and usable documentation out of plain text files
• ReadTheDocs:  Is a documentation host that can be attached to a public Git repository
• Draw.io, LibreOffice Draw, Dia: Produce diagrams, graphs, mind-maps, roadmaps, planning, standards, and metrics
• Peek, Asciinema: Use commands for recording your terminal
• VokoscreenNG: Use mouse clicks and screen capture

Our favorite resources about open source Git cheat sheet Advanced Linux commands cheat sheet Open source alternatives Free online course: RHEL technical overview Check out more cheat sheets Documentation is vital

Documenting processes and protocols are just as important as documenting your project itself. Most importantly, make information about your project and creation of your project exciting.

The speed of entering into a project and process, and understanding how everything works, is an important feature. It helps ensure continued engagement. Simple processes and a clear understanding of what needs to be done is obtained by building one "language" in the team.

Documentation is designed to convey value, which means demonstrating something through words and deeds. It doesn't matter whether it's a member of your team or a user of your application.

Think about the process as a continuum and use means of communication, processes, and documentation.

Image by:

(Olga Merkulova, CC BY-SA 4.0)

Documentation is a means of communication.

Establishing good documentation can be difficult, but it's critical to effective communication. Follow this framework for writing and sharing documentation with the right people.

Image by:

Opensource.com

SCaLE Documentation What to read next This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License. Register or Login to post a comment.

How I returned to open source after facing grief Amita Thu, 03/16/2023 - 03:00

The open source community is a wonderful place where people come together to collaborate, share knowledge, and build amazing things. I still remember my first contribution in Fedora 12 years ago, and since then it’s been an amazing journey. However, life can sometimes get in the way and cause us to take a break from participation. The COVID-19 pandemic has affected us all in different ways, and for some, it has been a time of immense loss and grief. I lost my loved one during the pandemic, and it has been the most difficult life event to deal with. It caused me to take a break from the Fedora community, as well. For those in the open source community who have had to take a break due to the loss of a loved one, returning to coding and contributing to projects can feel daunting. However, with some thought and planning, it is possible to make a comeback and once again become an active member of the community.

First and foremost, it is important to take care of yourself and allow yourself the time and space to grieve. Grief is a personal and unique experience. There is no right or wrong way to go through it. It is important to be kind to yourself. Don’t rush into things before you are ready.

Once you’re ready to start contributing again, there are a few things you can do to make your comeback as smooth as possible.

Reach out to other contributors

This is a hard truth: nothing stops for you and technology is growing exponentially. When I rejoined Fedora recently, I felt the world had changed around me so fast. From IRC to Telegram to Signal and Matrix, from IRC meetings to Google Meet, from Pagure to GitLab, from mailing lists to discussion forums, and the list goes on. If you haven’t been active in your community for a while, it can be helpful to reach out to your friends in the community and let them know that you’re back and ready to contribute again. This can help you reconnect with people and get back into the swing of things. They may have some suggestions or opportunities for you to get involved in. I am grateful to my Fedora friend Justin W. Flory, who helped me out selflessly to ensure I found my way back into the community.

Start small

In the past, I served as Fedora Diversity, Equity, & Inclusion (D.E.I.) Advisor, which is one of the Fedora Council member positions. It was a big job. I recognized that, and I knew that were I to think of doing the same job immediately after my break, then it would have been a burden that could threaten to cause early burnout. It’s vitally important to take it easy. Start small.

If you’re feeling overwhelmed by the thought of diving back into a big project, start small. There are plenty of small tasks and bugs that need to be fixed, and tackling one of these can help you ease back into the community.

Find a mentor

If you’re feeling unsure about how to get started or where to focus your efforts, consider finding a mentor. A mentor (in my case, Justin W. Flory) can provide guidance, advice, and support as you make your comeback.

Show gratitude

An open source community is built on the contributions of many people. A healthy community is grateful for your contribution. Showing gratitude is part of making a community healthy. Show your gratitude to others who help you, guide you, and give you feedback.

Block your calendar

Initially, it may take some time to get back to the rhythm of contributing. It helps to schedule some time in your calendar for open source work. It can be weekly/bi-weekly, depending on your availability. Remember, every contribution counts, and that is the beauty of the open source world. This trick will help you to get into a regular routine.

Two steps forward, one step back

Finally, it’s important to remember that it’s okay to take a step back if you need it. Grief is not a linear process. You may find that you need to take a break again in the future. It’s important to be honest with yourself and others about your needs. Take the time you need to take care of yourself.

Our favorite resources about open source Git cheat sheet Advanced Linux commands cheat sheet Open source alternatives Free online course: RHEL technical overview Check out more cheat sheets Return on your own terms

Returning to the open source community after a period of grief can be challenging. It’s also an opportunity to reconnect with something you are passionate about and make a positive impact in the world. In time, you’ll find that you’re able to pick up where you left off, and re-engage with the community once again.

I dedicate this, my first ever Opensource.com article, to my late younger brother Mr. Nalin Sharma, who left us at the age of 32 due to COVID-19 in 2021. He was a passionate engineer and full of life. I hope he is in a better place now, and I am sure he will always be alive in my memories.

Contributing to open source projects after losing a loved one can feel daunting. Here's my advice for how to rejoin the community.

Image by:

Opensource.com

Careers What to read next This work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License. Register or Login to post a comment.

Microsoft Makes Kubernetes-Based Edge Computing Platform Generally Available  Forbes

The post How to Mount Windows/USB NTFS Partition in RHEL Systems first appeared on Tecmint: Linux Howtos, Tutorials & Guides .

Are you trying to access an NTFS partition or NTFS formatted USB drive on an RHEL-based operating system, and have encountered an error? Do not worry, all will be fine once you finish reading

The post How to Mount Windows/USB NTFS Partition in RHEL Systems first appeared on Tecmint: Linux Howtos, Tutorials & Guides.

Steam Deck Now Lets You Transfer Games from PC over Your Home Network  9to5Linux

All-Open Source 7-Inch MNT Reform Pocket Laptop Ships In October  Slashdot

Transmission 4.0.2 Limits In-Kernel File Copying to 2GB Blocks at a Time, Fixes Bugs  9to5Linux

Following the PyTorch Foundation talking up PyTorch 2.0 since the end of last year, today marks the PyTorch 2.0 release officially shipping. PyTorch 2.0 has significant optimizations to "supercharge" it with better performance for both CPU and GPU modes of operation...