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.
Extra issues can include items related to the following:
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.
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.
When writing GNU Linux Documentation, use GNU Linux tools. Some tools available in your content creator toolbox include the following.
|scrot||SCReenshOT||screen capture in the background|
|nano||Nano's ANOther editor||quick editing - free Pico clone|
|gimp||GNU Image Manipulation Program||photo editor|
|simplescreenrecorder||Simple Screen Recorder||video capture tool|
|kdenlive||KDE Non-Linear Video Editor||quick video editing tool|
|vnc||Virtual Network Computing||remote management (for small board computing like pi*)|
|bash||Bourne Again SHell||shell and command language|
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* documentation created on Windows* systems is probably best.
Writing Linux* documentation using Windows* is not recommended. Understanding a system is essential.
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!
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:
For more information about the portable character set visit:
The following is a brief explanation about using the hyphen character and replacing Windows* characters for Linux*.
|Unicode (code point)||character||UTF-8 (hex)||name|
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.
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 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:
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.
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.
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!
Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.
Notice revision #20110804