FOSS Content Creator: Writing for GNU Linux* using GNU Linux*

Write for the Associated Product

When writing for a particular Operating System or even a particular distro, good practice dictates using the exact same platform. For example, do not write Ubuntu* documentation using Windows*. Write Ubuntu* related documentation using Ubuntu. This process could even go a little deeper into using the same system requirements the documentation requires developers to use. For example, if the developer instructions require kernel 4.15, use kernel 4.15 with the distro to capture screenshots, test results, and write the documentation. Today, less building using backports. It's easier than you may think! 

With the right tools, on the right platform, documentation does not incur "extra issues". Working across multiple operating systems can cause these issues. If issues are not caught in time by content creators who "know this stuff", or if issues are neglected during the review process, the result can cause commands or code to fail! 

This can be avoided by using the system you are documenting.

What are "extra issues"?

Extra issues can include items related to the following:

• Formatting/Styles
• Font
• Odd Characters

Using a different Operating System for content creation, is not as effective and efficient as using the same OS. Additionally, this cross system use can result in unintended consequences. The end result is not optimal.

Examples:

A Windows* writer may not catch a character that will not work in bash.

A GNU Linux* writer may not perform at the highest level when using Windows* tools and utilities. 

A MacOS* writer may not be familiar enough with another system to write about it. 

The ideal situation is when the content creation happens on the platform or system being documented with the creator familiar with the product and system. 

GNU Linux - FOSS (Free and Open Source)

When writing GNU Linux Documentation, use GNU Linux tools. Some tools available in your content creator toolbox include the following.

MacOS  - Proprietary Cocktail, Controlled ecosystem

MacOS documentation using a MacOS system is likely best. I do not have a lot of experience in this area. Many of the tools available in GNU Linux are also available with MacOS, often using brew install. 

The command line is available and navigating the system is similar to GNU Linux. There are no command or code snippet issues in my experience across MacOS and GNU Linux. Paths are a little different.

Windows*  - Proprietary

Windows* documentation created on Windows* systems is probably best.

Writing Linux* documentation using Windows* is not recommended. Understanding a system is essential.

Brand or Command?

If someone is familiar with a GUI or Windows* system, but unfamiliar with the command line, this content creator may not realize: a trademark is not used with a command.

Understanding the difference between a brand, and a command is essential!

What is POSIX?

POSIX, or Portable Operating System Interface is a collection of IEEE standards for Unix and Unix derivatives like GNU Linux. The standards have included the following:

• Shell Language
• Environment Variables
• Regular Expression
• Directory Structure
• Filenames
• ANSI C extension
• CLI Utilities
• Command Line API conventions
• Program Exit
  • EXIT_SUCCESS! and more!

For more information about the portable character set visit:

https://en.wikipedia.org/wiki/Portable_character_set

Script to Search and Replace Windows* characters

The following is a brief explanation about using the hyphen character and replacing Windows* characters for Linux*.

UTF-8

Hyphen or dash?

A hyphen joins two or more words. A dash has a space on either side.

The the term hyphen was used in this documentation because of the width of the hyphen, although we sometimes call it a dash.

The en dash is short dash, the width of an en or half the width of an em dash (a little circular definition).

The em dash is, therefore, twice the width of an en dash.  See below for more information.

Operating System Specific

The hyphen character used in Linux*:         

-

The hyphen character converted from Linux on a Windows* system:     

–

The Windows* character will not work in bash.

To fix all the instances in the content, you can:

• Manually check the files
• Run a simple grep and sed command at the terminal
• Write a simple script to find and replace the hyphen

Manually checking files is more time consuming and leaves room for error. Writing and running a script, when done right, will save time and catch all the errors.

Figure 1. GUI version (YAD) of the script.

A simple script to replace the non-functional hyphen is provided.

The attachment includes:

• filename.md
  • a file with the wrong hyphen to demonstrate the script works
• bash script
• Optional: bash script with YAD for simple GUI

Extract the files and run either script.

Note: Scripting will save time and catch all the instances of the wrong non-functional hypen created by proprietary software during the documentation process.

Best Practice

The best practice, when creating GNU Linux* docs, is:

GNU Linux* writers use GNU Linux* for documentation to avoid errors and to create great FOSS content!

The best practice, for Developer Experience (DX) Testing for GNU Linux* docs is:

Understand your audience to hit the right participant pool. Experienced GNU Linux developers or users who understand the content are the most effective to conduct the DX testing and evaluate the results. These qualified GNU Linux DX professionals are best to provide recommendations for edits to the documentation. 

Next Steps

If you are interested in exploring writing for different operating systems, throw up a virtual machine or container! Try out some of the tools, applications and utilities. As always understand the content you write!