Kullanıcı:Hatas/Wiki experiences for Linux distributions
|
This page is translated by Google Translate. (see original text) |
When we examine the community documentation centers (wiki pages) of various Linux distributions serving in Turkish or English language, we see that many of the similar errors are repeated. Some important errors or irregularities can be listed as follows: Not to go down to the end user level in the documents (distribution, targeting the desktop users, but the issues are explained through the command line), the main purpose of the site without questioning the Linux and free software, including all kinds of articles related to the format and expression it speaks different languages.
As a contributor who has worked actively for more than a decade on the community documentation sites of various Linux distributions, I would like to share some of my experiences with this article. Wishing to be useful ...
Suggestions
The following list many suggestions on the Ubuntu wiki Turkey in a 'Policy' brought into the matter. In the documentation center where you are a contributor, you can transform your principles into written policies.
1. Do not explain the operations that can be done with the interface through the commands
Before you begin the documentation work, start by searching for the answer to this question: Is this deployment targeted at desktop users or a distribution for more professional users (such as Slackware, Arch, Gentoo)?
If the target audience of the distribution is desktop computer users, you should stay away from the command line as much as possible in the documents you will prepare and tell the issues through the graphical interface. For example, you should not describe the installation of an application that can be installed via the package manager graphical interface via the command line. Unfortunately, in the Linux wiki pages of most Linux distributions, we come across documents that describe almost the simple cut-and-paste operations via the command line. "How to install Gimp? " Open the terminal and give the command sudo apt-get install gimp...
It may be possible to do a job that can be done with 10 mouse clicks at the interface with two clicks from the command line, but this does not exclude the fact that the command line is an expert user tool. A desktop user who doesn't use the command line all the time will probably forget about the one-line command shown to him after a few minutes. A process that can be done with 5-10 clicks over the interface may not be forgotten for a long time.
2. Do not aim to increase the number of articles, focus on content quality
Article is easy to write; it is difficult to produce an attentive, quality document. Article is easy to write, it is very difficult to keep up to date. If you have fewer articles, you can produce better quality documents and keep them up to date. You don't need hundreds of items to keep your desktop empty-handed, and 30-40 core documents that you need to create will be enough to back your Vikin.
The documentation pages of many Linux distributions, including Ubuntu Turkish Wiki, are often licensed under free content licenses such as Creative Commons and GNU GPL. Therefore, under the terms of the license you can copy the content you like on these sites and adapt it to the Linux distribution you contribute. Some free content licenses require you to refer only to the original source of the copied content and license the content you upload with the same or similar license, while some free software licenses may not allow the content to be copied for commercial purposes. The requirements for commonly used free software licenses for copying are described in the following sections.
If you are documenting a deployment that is addressed to desktop users, such as Ubuntu, you can give priority to the following issues when starting out.
- The definition of distribution, by whom it is developed, whether it is paid or not, license etc. can be accessed from the main page. open a question-and-answer article about topics (examples: What is Ubuntu?, About Debian).
- In a way that a user who has never installed Linux in his life can understand; Prepare documents describing each step of installing the system and provide a link from the main page to access them (see Installation). UbuntuViki contains up to 10 items related to the installation topic, and these are the most frequently clicked items.
- To teach Linux usage to a user who has never used Linux in his life, prepare a tidy - two documents that go down to the end user level, such as Ubuntu getting started guide and Frequently asked questions and link to the home page.
After preparing and completing these documents carefully, you can take a breath, you now have a documentation center!
3. Do not rewrite articles in Wikipedia. Give the Interviki connection!
Especially when we look at community-based Linux wiki projects, we see that many of the software and Linux-related concepts that can be used in Linux are tried to be explained repeatedly.
- Almost all Firefox, LibreOffice, Gimp, VLC, K3b, KolourPaint, Blender, Inkscape We see. For example, for Firefox, five separate Linux distribution communities in the Turkish language open five separate introduction pages. This loss, the loss of free software only in the Turkish language, and multiply it by dozens of languages, can you imagine how much effort is wasted? As a concrete example; Pardus The PardusWiki community site, which is active between 2005 and 2012, is not currently live (see Web archive) around 450 application introduction items were once written.
- The biggest loss of effort in repetitive content in Linux distribution wiki stems from software introduction materials. Of course, we don't have any other lost-illegal items.
- In many of them we see a page about Linux related or related concepts. For example: Linux, free software, open source, GNU, Unix, KDE, Xfce, Linux distribution, operating system, Android, such as iOS.
- We see some of them open articles about various free software-content licenses. For example: GPL, LGPL, BSD license, Creative Commons, Apache License, MIT License.
However, there are countless articles in Wikipedia on all these issues. Ubuntu Wiki site in Turkey have taken an important step to put an end to these losses. First, Policies and guidelines by preparing the page we've agreed to the following principles: " 'identification unless the application is not essential in the ubuntuvi on-site material does not include the diverted instead to users on Wikipedia about.' '" In the policy statement, We have also clarified the necessary conditions and explained in which cases a software introduction material can be opened.
To make it easy for users to link to Wikipedia, we've done a little editing (*) in UbuntuViki. This means that when we add the "v:" prefix to the beginning of an internal link in UbuntuViki, we automatically redirect that link to the Wikipedia page. For example, when we want to link to "LibreOffice" in Wikipedia, we write [[v:LibreOffice|LibreOffice]]. When we write this, the result is: LibreOffice. So we don't have to open an item called LibreOffice in UbuntuViki.
 Special:Interwiki page (*) Any contributor with a retainer authority on a Viki site can go to the Special:Interwiki page and make the Turkish Wikipedia an interviki link. However, in order to see and use the Special:Interwiki page, you must have the extension of the site administrator Extension: Interwiki enabled on your wiki. I also need to add the following line to the file LocalSettings.php which is located in the MediaWiki installation folder:
Any user with retainer privileges now enters the Special: Interviki page and defines a prefix for Wikipedia by clicking the corresponding button, enters the URL address, then activates the forwarding option. |
4. Determine the boundaries of what kind of documents can be included
In a Linux distribution wiki, there should be a clear limit on what kind of items can be used, and not on issues outside the general framework of the distribution. Concrete examples of issues that are appropriate and not appropriate to be opened under the operating system documentation:
- It is not appropriate to open articles for application promotion:
Firefox- LibreOffice
- Gimp
- It may be necessary to give notes and hints to help users about software such as File Manager and Terminal. For example, how to show hidden files in the file manager. Since it would not be appropriate to describe such information in the Wikipedia, an introduction to the software may be opened in UbuntuWiki.
- It is appropriate to describe the installation of applications that are not available in the application store and therefore require additional installation. Because such content cannot be included in the Wikipedia.
- It is not appropriate to prepare guidelines for the use of applications:
- Basic audio editing with Audacity
- CD / DVD burning and basic operations with Brasero
- Gimp lessons 1, Gimp lessons 2, Gimp lessons 3, Gimp lessons 4
- General settings of the operating system, troubleshooting problems and so on. The opening of ingredients in matters is appropriate:
Repair the Grub boot loader- How to install software in Ubuntu?
- Add icon set
- Manual wireless network configuration
- It is not appropriate to create detailed lists of application types (see Internet applications). We have created such pages in UbuntuVik in the past, but it is almost impossible to keep such lists up-to-date and include the most popular applications in all areas.
We've defined our policy on the Policy and guidelines page, albeit a little late on Viki, and you can follow a similar path.
5. Using upper and lower case letter
In a wiki that doesn't have any policies about naming the pages and the use of upper and lower case letters in the sub-headings within the page, you may inevitably encounter various kinds of headings as below.
- LINUX INSTALLATION (FALSE)
- LINUX Installation (FALSE)
- Linux installation (TRUE)
When creating a new page in Wikipedia (including category, template pages), the page name starts with a capital letter, the next letters and words are written in lowercase letters (the first letter of special names is capitalized in accordance with the Turkish spelling rules). The same policy applies to sub-topics within the page. Try not to deviate from the principles adopted in Wikipedia on these and similar Formatting topics. Thus, users with Wikipedia culture can easily contribute to your wiki.
6. Carrying out maintenance and update works
Prepare a Category: Construction and maintenance like category and templates {{Update}} , {{Quality}} , {{Draft}} , {{Delete}} as we have created in UbuntuViki, for the maintenance of the pages, that is, the items that need to be updated, developed or deleted, and managed.
Once you've installed this system, users in your wiki can easily label any page that needs updating, deletion, or other maintenance, adding one of the {{Update}}, {{Quality}}, {{Draft}}, {{Delete}} templates to the beginning of that page. Pages tagged in this way are automatically listed under the respective maintenance category.
7. Help documentation for wiki authors
In the Wikileaks project that serves dozens of different fields from science to art, from history to technology Help section is like a whirlpool you turn from there to there, you feel that there is no end to the help documents. In UbuntuViki Help we went to the documentation of basic topics that might be needed to do wiki writing. In the wiki pages of any free software project, you can go to the documentation of basic help topics just like we do in UbuntuViki, or you can direct contributors who want to get help directly to Wikipedia.
8. Guidelines for contributing to wiki
For users who want to contribute, create a guide like Contribute to UbuntuWiki to indicate what work is needed on your wiki and link where appropriate.
9. Community portal to discuss general topics
In order to discuss technical and administrative issues, the wiki-related suggestions, such as the "Community portal", etc. Open a discussion page under a name, or use the Home page's discussion page for such topics (UbuntuViki does not open a community portal because such discussions are conducted through the forum ). Place the community portal link in the site interface, accessible from each page (see MediaWiki:Sidebar).
It is possible that some important discussions concerning the wiki general will begin on other pages. If you come across such a discussion that concerns the wiki in general, bring the content of the discussion to the community portal.
10. Lists of supported / unsupported hardware
In the English-language documentation centers of several major Linux distributions, settings such as laptops, printers / scanners, graphics cards, sound cards, hardware, etc., under the X-version of the Linux distribution (whether they are working properly or not) etc.). For example, in the OpenSuse wiki Laptops, this type of work is being carried out, with Ubuntu in the past UbuntuWiki / HardwareSupport, UbuntuWiki / Laptops provided information about hardware support. Ubuntu later moved to the official Ubuntu Certified Hardware professional project.
Preparing such pages for a Linux distribution and keeping the page up-to-date by testing the hardware in each new release is not something to do with a few volunteer contributors. In the past, the PardusWiki community documentation center, which was closed in 2012 for Pardus Linux distribution, has attempted a similar work in the past. Many contributors opened a page about the computers and hardware they used, and added information about whether the hardware is working properly under version X of Pardus. In this way, nearly 200 documents were prepared, but almost none of the documents were updated in the new Pardus versions.
Preparing and following such documentation for hardware support is a major task. If you create such content on the community documentation site, this information will probably be in need of maintenance within a few years. It is appropriate that you do not include such documents in your Wiki and use the forum pages for such information.
Preparing and following such documentation for hardware support is a major task. If you create such content on the community documentation site, this information will probably be in need of maintenance within a few years. It is appropriate that you do not include such documents in your Wiki and use the forum pages for such information.
11. Using screenshots in documents
Take the screenshots that you will use in the documents you will prepare over the default conditions of the operating system and applications. Wallpaper, window decoration, color theme and so on. Do not take screenshots from a personalized environment by changing the properties. You don't have to undo all of the personalizations you've made to return to the default desktop. The most practical way is to add a new user to the system. You can easily take screenshots from the default desktop environment by logging in with this user when necessary.
On the other hand, screenshots are one of the most important obstacles to keeping a documentation center up to date. For this reason, use enough screenshots in the documents you prepare.
12. Content license of the site
In accordance with Linux and free software, you are also required to license the content (texts, images, etc.) in the documentation center you are installing with a free content license. The most widely used public content license worldwide is Creative Commons. There are several types of this license. For example:
- Creative Commons BY-SA: There are two requirements; the first owner of the work will be specified (by), the first license model will be maintained (h). In accordance with the SA requirement, all copies of the work or new works produced from the work must be published under the same, similar or compatible license. Therefore, this condition ensures that the work or the works derived from the work is always free.
- Creative Commons BY-NC: There are two requirements; the first owner of the work will be specified (by), can not be used for commercial purposes (nc)
- Creative Commons BY-NC-SA: There are three requirements; the first owner of the work will be specified (by), can not be used for commercial purposes (nc), the first license model will be retained (sa)
The BY-SA model of these licenses is accepted by the Free Software Foundation as a free license model in accordance with GNU philosophy. Wikipedia is a type of license that is also used in Wikipedia projects. There is no commercial restriction in this license. In fact, the GNU Draft does not oppose monetization, provided that the license complies with the requirements of the license (specifying its source, always keeping it open to everyone with a free license). As a result, you should use the Creative Commons BY-SA license in accordance with the free software - free content philosophy.
You may find that some free software wikis use the GNU FDL license instead of Creative Commons BY-SA. This license issued by the Free Software Foundation shows great similarities to CC BY-SA. When I examine both licenses, the main difference I have identified is; Copies of the work published by CC BY-SA can be published under the same, similar or compatible license, while copies of a work published with GNU FDL need to be used again.
In Ubuntu Wiki, some remarkable documents
Wiki addresses of some Linux distributions
Below are the addresses of the "official" or "community" documentation centers of some Linux distributions.
| |
| Antergos | |
| ArchLinux | |
| Debian | |
| CentOS | |
| Deepin | |
| Fedora | |
| Gentoo | |
| LinuxMint | |
| Mandriva |
|
| Mageia | |
| Manjaro | |
| OpenSUSE | |
| PCLinuxOS | |
| Red Hat | |
| Sabayon | |
| Ubuntu |
|
Posted on: 24 Ocak 2014 (Original Turkish text)
Posted on: 24 Temuz 2019 (English text)
I license this content under CC BY-SA license. --Hatas (message)