magazine/fedora-magazine
1
1
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

init

Browse source
This commit is contained in:
Adam Samalik 2019-06-04 16:06:42 +02:00
commit a917f435a5
16 changed files with 430 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored Normal file
View file

@ -0,0 +1,3 @@
build
cache
public

57
README.md
View file

@ -1,3 +1,56 @@
# fedora-magazine
# Fedora Magazine docs
Resources for the Fedora Magazine editorial board
This repository contains sources of the [Fedora Magazine documentation](https://docs.fedoraproject.org/en-US/fedora-magazine/).
## Technical information
```
|-- README.md
|-- antora.yml ....................... 1.
|-- build.sh ......................... 2.
|-- preview.sh ....................... 3.
|-- site.yml ......................... 4.
`-- modules
`-- ROOT ......................... 5.
|-- assets
| `-- images ............... 6.
| `-- pizza.png
|-- nav.adoc ................. 7.
`-- pages .................... 8.
|-- index.adoc
|-- page.adoc
`-- another-page.adoc
```
1. Metadata definition.
2. A script that does a local build. Uses docker.
3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker.
4. A definition file for the build script.
5. A "root module of this documentation component". Please read below for an explanation.
6. **Images** to be used on any page.
7. **Menu definition.** Also defines the hierarchy of all the pages.
8. **Pages with the actual content.** They can be also organised into subdirectories if desired.
### Local preview
This repo includes scripts to build and preview the contents of this repository.
**NOTE**: Please note that if you reference pages from other repositoreis, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions.
Both scripts work on Fedora (using Podman) and macOS (using Docker).
To build and preview the site, run:
```
$ ./build.sh && ./preview.sh
```
The result will be available at http://localhost:8080
### Installing Podman on Fedora
Fedora Workstation doesn't come with Podman preinstalled by default — so you might need to install it using the following command:
```
$ sudo dnf install podman
```

16
antora.yml Normal file
View file

@ -0,0 +1,16 @@
# Name will be mostly visible in the URL. Treat it as an indentifier.
# Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page)
name: fedora-magazine # <---- PLEASE MODIFY
# Title will be visible on the page.
title: Fedora Magazine # <---- PLEASE MODIFY
# If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.
version: master
# We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise.
start_page: ROOT:index
# This lists all the menu definitions of your component.
nav:
- modules/ROOT/nav.adoc

46
build.sh Executable file
View file

@ -0,0 +1,46 @@
#!/bin/sh
image="docker.io/antora/antora"
cmd="--html-url-extension-style=indexify site.yml"
if [ "$(uname)" == "Darwin" ]; then
# Running on macOS.
# Let's assume that the user has the Docker CE installed
# which doesn't require a root password.
echo ""
echo "This build script is using Docker container runtime to run the build in an isolated environment."
echo ""
docker run --rm -it -v $(pwd):/antora $image $cmd
elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then
# Running on Linux.
# Check whether podman is available, else faill back to docker
# which requires root.
if [ -f /usr/bin/podman ]; then
echo ""
echo "This build script is using Podman to run the build in an isolated environment."
echo ""
podman run --rm -it -v $(pwd):/antora:z $image $cmd
elif [ -f /usr/bin/docker ]; then
echo ""
echo "This build script is using Docker to run the build in an isolated environment."
echo ""
if groups | grep -wq "docker"; then
docker run --rm -it -v $(pwd):/antora:z $image $cmd
else
echo ""
echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password."
echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/."
echo ""
sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd
fi
else
echo ""
echo "Error: Container runtime haven't been found on your system. Fix it by:"
echo "$ sudo dnf install podman"
exit 1
fi
fi

7
modules/ROOT/nav.adoc Normal file
View file

@ -0,0 +1,7 @@
* xref:contributing.adoc[Contributing]
** xref:getting-access.adoc[Getting access]
** xref:writing-a-pitch.adoc[Writing a pitch]
** xref:writing-an-article.adoc[Writing an article]
** xref:creating-an-image.adoc[Creating a featured image]
* xref:tips-for-writers.adoc[Tips for writers]
* xref:editorial-meetings.adoc[Editorial meetings]

18
modules/ROOT/pages/contributing.adoc Normal file
View file

@ -0,0 +1,18 @@
= Contributing to the Fedora Magazine
Fedora Magazine welcomes contributions of content relevant to Fedora Users.
Before the first contribution:
1. xref:getting-access.adoc[**Get access**:] You need to have access to our Wordpress in order to contribute.
Writers' steps:
2. xref:writing-a-pitch.adoc[**Write a pitch**:] Propose your idea to the editorial board and get it accepted.
3. xref:writing-an-article.adoc[**Write the article**:] Write your article following the recommendations and let the editorial board know when you're ready.
Editors' steps:
4. **Edit the article**: An editor makes sure the article reads well, checks facts, and corrects typos.
5. xref:creating-an-image.adoc[**Create an image**:] Each article gets a cover image before its published.
6. **Schedule the article**: Finally, the article is scheduled for publishing!

62
modules/ROOT/pages/creating-an-image.adoc Normal file
View file

@ -0,0 +1,62 @@
= Creating a featured image for the Fedora Magazine
Each article in the Fedora Magazine must have a featured image. The image gives the article added visual appeal. It also appears in links on social media, to attract more viewers.
These images are created as SVG (scalable vector graphic) images. To work with these images, you should install a SVG capable application such as Inkscape[Inkscape]. You will also need the git[git] utility installed.
== Getting the image repository
Open a Terminal. (You’ll type commands into the terminal for some of the following steps.)
Install the git and inkscape packages if you don’t have them installed already:
$ sudo dnf install git inkscape
If desired, change directory into the folder where you like to store your project work. This example uses the folder name projects, but you should use a folder you have on your system. This step is optional:
cd projects
Now clone the git repository of Fedora Magazine images:
$ git clone https://pagure.io/fedoramagazine-images.git
== Creating a new image using the template
Open Inkscape, and choose File > Open… (or hit Ctrl+O). Navigate to the project folder, then into fedoramagazine-images, then into images. Choose the template.svg file.
Save this as a new file with a different name.
You can use the assets inside this file to start with the right-sized document, with some pre-configured backgrounds. Feel free to look at other SVGs for guidance. If you don’t have experience with these images, try to stick with fonts and motifs that you see in recent banners. But also feel free to experiment! For instance, use photographs (freely licensed, such as CC-BY or CC-BY-SA) with a text overlay for a nice look. https://unsplash.com/[Unsplash.com] has a large library of images in the public domain you can use to get started.
=== Fonts
There are a few fonts that are commonly used in featured images. You are encouraged to use these fonts in your images to help featured images fit into the general “theme” that other images follow. They are all freely available at the links provided. The fonts we commonly use on the Fedora Magazine are listed below.
http://www.fontsquirrel.com/fonts/montserrat[Montserrat] (friendly and Sans-like)
http://fontsquirrel.com/fonts/roboto-slab[Roboto Slab] (friendly with serifs)
http://www.fontsquirrel.com/fonts/molot[Molot] (heavier font, feels technical)
http://www.fontsquirrel.com/fonts/grand-hotel[Grand Hotel] (for a fancy script-y feel)
To use these fonts on your Fedora system, download the font and unpack the OTF or TTF file (if required) into your ~/.fonts folder. Then update your font cache:
$ fc-cache
You will need to close and reopen Inkscape, GIMP, or other applications to take advantage of the new fonts.
== Getting your work reviewed
If you’d like to post your work somewhere, convert it to a JPG first. This will typically be a smaller file. Make sure your SVG file is saved in the fedoramagazine-images/images/ folder as above. Typically these should be named after the article in some way to make it easier to find images later. For this example, let’s assume your SVG file is named using-inkscape.svg.
Open a Terminal and go to the fedoramagazine-images/images/ folder:
$ cd projects/fedoramagazine-images/images/
Now use the helpful make target we’ve provided. This creates the correct sized (1890x800 pixels) JPG automatically, if you provide the same name as your SVG file:
$ make using-inkscape.jpg
Now you can post this file, using-inkscape.jpg, online, and then provide that URL to the mailing list for review. Remember, don’t attach your JPG to a mailing list post. URLs are the correct way to have your file reviewed.

34
modules/ROOT/pages/editorial-meetings.adoc Normal file
View file

@ -0,0 +1,34 @@
= Fedora Magazine editorial meetings
The goal of this meeting is to set and execute a publishing schedule of appropriate material for the Fedora Magazine.
== Agenda
Typically we practice the same agenda each meeting:
1. Retrospective of last week's publishing and stats
** Ensure all posts were echoed to social media
** If any pending, reviewed stories are not published, schedule and assign social media duty
** See if any first time writers have been published and make a badge request if so
2. https://fedoramagazine.org/wp-admin/edit.php?post_status=pitch&orderby=date&order=asc[Pitch votes] (starting with oldest)
** GOAL: Determine whether pitch is appropriate for a story, and if so, move to Draft status and set publication date
** Include pitches in feedback
** If not, either:
*** Trash pitch, and assign someone to respond to author to thank them
*** Assign someone to work with author to refine story idea
3. https://fedoramagazine.org/wp-admin/edit.php?post_status=draft&post_type=post&orderby=date&order=asc[Drafts not finished] (starting with oldest)
** GOAL: Determine if draft is ready for final review, and if so, move to Pending Review status
** If not:
*** If author is still working, editor is responsible for ensuring completion
*** If author is MIA for 2nd week, drop back to Pitch and rearrange publication schedule
** Assign for review and set to Pending Review status
** Review/set publication date and add to schedule
4. https://fedoramagazine.org/wp-admin/edit.php?post_status=pending&post_type=post&orderby=date&order=asc[Pending Review] (starting with oldest)
** Confirm editor deadline
** Review/set publication date and confirm schedule
== Exceptions
The following types of articles generally can route around the weekly meetings. This helps us get critical information out to the audience without waiting for the next board meeting.
* **Security updates:** Critical security updates that affect a broad user audience are pre-authorized. Generally an editor will write the update article. If possible, one other editor does a quick spot check. If that would affect the timing, however, the posting editor simply publishes the article and notifies the magazine list. An example is a Firefox security issue.

9
modules/ROOT/pages/getting-access.adoc Normal file
View file

@ -0,0 +1,9 @@
= Getting access
**1. Get a Fedora FAS Account**: If you don’t already have one, sign up for a https://admin.fedoraproject.org/accounts/user/new[Fedora Account System (FAS) account here].
**2. Sign in to the Fedora Magazine**: Now, using your FAS Account, https://fedoramagazine.org/wp-admin/[sign in to the Fedora Magazine here].
**3. Join the Magazine list and introduce yourself**: Next up, subscribe to the https://lists.fedoraproject.org/admin/lists/magazine@lists.fedoraproject.org[Fedora Magazine mailing list]. This is where we discuss everything to do with the Fedora Magazine. Introduce yourself and tell us that you wish to contribute to the Fedora Magazine. A Fedora Magazine editor will then grant you access to create and edit posts, and submit them for review.

26
modules/ROOT/pages/index.adoc Normal file
View file

@ -0,0 +1,26 @@
= Fedora Magazine
http://fedoramagazine.org[Fedora Magazine] is a WordPress-based site which delivers all the news of the Fedora Community. (It replaced the older publication, Fedora Weekly News.)
== What is the content of the Magazine
The content of the magazine varies, but mostly includes:
* General Announcements / News
* Tips on how to use software in Fedora
* Ideas for cool apps to try
* Ways to more effectively develop software using Fedora
* DIY hardware projects you can power with Fedora
* ... And everything else related to Fedora in general!
== Join the Magazine Team
We really need your help on the Magazine. Consider xref:contributing.adoc[writing an article]. You'll also find a link for how to join the marketing mailing list at that link. There is also a detailed guide on how to make a post on the magazine.
We also have regular xref:editorial-meetings.adoc[editorial board meetings].
* IRC Channel: https://webchat.freenode.net/?channels=#fedora-magazine[#fedora-magazine]
* Mailing list: https://lists.fedoraproject.org/admin/lists/magazine@lists.fedoraproject.org/[magazine]

70
modules/ROOT/pages/tips-for-writers.adoc Normal file
View file

@ -0,0 +1,70 @@
= Tips for article style, grammar, content, and SEO
These tips will help your article sail through editing. Be kind to your editor(s), and read this before you start.
== Markup
Primary rule: don’t get too fancy. Legibility is important.
1. **Don’t mix monospace fonts with proportional fonts in a sentence.** Use italics for the special text. For instance, don’t write dnf install foo in the middle of a sentence, write dnf install foo.
2. **Use italics for system objects you mention in a sentence:**
** GUI or CLI elements like button text or menu entries
** other prompts the reader must find on the screen
** commands or package names
3. **Use the Preformatted style in the WordPress editor for command line input or output.** Use a shell prompt ($ or #) only where it genuinely affects the meaning, or to set the input apart from output. It also helps to use boldface for the input itself:
+
[subs=quotes]
----
$ **command arg1 arg2**
output line 1
output line 2
----
4. **Use boldface only for an extremely important phrase or statement.**
== Grammar and style tips
1. **Use sentence case for the post title and heading titles.** Don’t capitalize words in your article title or any heading, other than proper nouns. This avoids needless arguments about title case, which differs by region.
** Incorrect heading: __Use Sentence Case for Post Titles in Fedora Magazine__
** Correct heading: __Use sentence case for post titles in Fedora Magazine__
2. **Check spelling and grammar.** Nobody likes nitpicky comments about this. Check your work before you send it to an editor. Editors: double-check all the work, that’s your job!
3. **Write clearly and use shorter sentences.** Brevity is good. Clarity is better. Don’t be excessively wordy when avoidable. If a longer sentence is easier to read, use the extra words.
4. **Avoid passive voice.** Passive voice is the use of the object of a sentence as the subject. For example:
** __Active voice__: The troops defeated the enemy.
** __Passive voice__: The enemy was defeated by the troops.
5. **Be careful of gerunds (-ing words).** They usually indicate passive voice. Rewrite your sentence to make it stronger. For example:
** __Weak, passive voice__: Setting the foobar configuration option will make the application listen on all interfaces.
** __Strong, active voice__: Set the foobar configuration option to make the application listen on all interfaces.
6. **Avoid too much use of the verb __to be__ in sentences.** Too much use of is, will be, or can be makes your sentences weak and flabby. Try using the verb form of words you’ve shuffled off elsewhere in the sentence. Often you can simply drop words, or use the imperative (commanding or advising) form of the sentence.
** __Weak__: Zambone is an app used for managing your private documents on a server.
** __Strong__: Zambone manages your private documents on a server. Or: Use Zambone to manage your private documents on a server.
** __Weak__: When setting up a file server, it is important to plan the directory structure carefully.
** __Strong__: Plan the directory structure of the file server carefully before you set it up.
7. **Use standard US English for spelling and other international differences.** US English is the lingua franca for the Fedora Project overall.
8. **Have a smooth flow from general information to specific instructions.** If you’re not sure how to structure your article like this, check out our starter template.
== Content tips
These tips are about things to do — and avoid — in what you tell users to do. Remember that thousands of readers trust Fedora Magazine to tell them how to carry out tasks. Be responsible and helpful, advocate best practices, and respect the user’s security and choice.
1. **Leave packaged files alone.** Processes should not involve editing files under system folders like __/usr__ or __/lib*__. Edit __/etc__ or a user-specific configuration in the home directory.
2. **Prefer free software where practical (and officially packaged software wherever possible).** The Magazine can still cover non-FOSS software to be used on Fedora, where we know or suspect that software is very popular and useful to Fedora users. (Google Chrome is a good example.) But if your article is covering a general process, use FOSS software.
3. **Use libvirt/KVM in tips, not VirtualBox or other hypervisors.** Frequently people coming from other platforms have VirtualBox experience. However, the KVM hypervisor and libvirt in Fedora are FOSS and part of the platform. Use them, write about them, love them.
4. **Unless necessary, use Fedora family distributions.** The Fedora Magazine promotes Fedora. Unless the point of your article is to specifically explain a cross-distribution mechanism, use installations, containers, or distributions within its family (Fedora, CentOS, RHEL).
5. **COPR software must be accompanied by a caveat.** The COPR build system is not managed by the Fedora release team and does not provide official software builds. If you cover some software from COPR, ensure there’s no official build. If not, include a statement like this:
** __COPR is not officially supported by Fedora infrastructure. Use packages at your own risk.__
6. **Test your process.** If possible, use a fresh guest VM — or at least a brand-new user account. Run your process from beginning to end to ensure it works. Fix, rinse, and repeat.
== WordPress tips
1. **Use a simple, relevant title.** Preferably this should be a call to action, like __Build a widget using GTK+__, or a list description, like __5 fun games in Fedora__. The title affects search engines, and leads to more hits and higher page ranking. That helps drive traffic to the Magazine.
2. **Provide a featured image.** Look at https://fedoramagazine.org/creating-a-featured-image-for-a-fedora-magazine-article/[the information here] for tips on featured images. You can also feel free to ask the editors to assign this for you. If you make your own image, try to match the style of other images. Use the assets provided https://fedoramagazine.org/creating-a-featured-image-for-a-fedora-magazine-article/[in the featured image guide]. Don’t add your own fonts or deviate from the guide.
3. **Use good SEO practices.** Use the SEO plugin provided to maximize the search ranking of the article. Aim for a “green” rating in the __Publish__ box at top right of your article’s edit screen. Follow these guidelines:
** Enter a meaningful keyword in the SEO box under your article. (Most articles shouldn’t use __Fedora__.)
** If the Snippet doesn’t give an effective introduction or summary in the sample search result, rewrite it.
** Don’t feel like you have to eliminate every warning. A “green” rating overall is the only goal.
== Other hints
Got an idea for better writing? Discuss with the editors on IRC Freenode at the #fedora-magazine channel.

24
modules/ROOT/pages/writing-a-pitch.adoc Normal file
View file

@ -0,0 +1,24 @@
= Writing a pitch for the Fedora Magazine
== What is a pitch?
A pitch is the first step for proposing a new article for the Fedora Magazine. If you are looking at getting started with the Magazine and are not yet familiar with what a pitch is, read how to begin contributing to the Magazine. Anyone who is ready to write a pitch should try to use the following format when writing their pitch. Using this format will ensure a speedy and easy review, and in the event that you do not plan to write the article, it will make it easier for a writer to hit key points.
== Writing a pitch
Create a new post with Pitch status in the Fedora Magazine WordPress interface. Pitch is the default status for a new post. In your newly-created post, write a brief outline of your post, what it will contain, and the target audience. The Fedora Magazine’s primary audience is Fedora users — including sysadmins and developers too. But in some cases we have content directed at both Fedora users and contributors.
Once you’re happy with your pitch, email the Fedora Magazine mailing list with a preview link to your pitch. The Magazine editors will review your idea and give you some feedback, and hopefully approve your idea for an article. We review pitches so you don’t waste time on writing a full article that turns out not to fit the Magazine in the end. **Don’t write the whole article** before this step. Let us help you focus it well for best results!
== Example Pitch
__The following article serves as an example outline for proposing a new pitch for the Fedora Magazine. This example was used for the https://fedoramagazine.org/never-leave-irc-znc/[Never leave IRC again with ZNC] article.__
**Summary**: Describe how to set up an IRC bouncer using ZNC
**Description**: The purpose of this article would be to describe what an IRC bouncer is and how someone can set up their own ZNC instance to connect to IRC networks and remain persistently connected to channels. The article would aim to educate the user about two things: what and how. Since IRC is a major communication platform for Fedora (and most free and open-source project communities), this article would ideally promote using IRC as well. The flow of the article would be as follows:
* What is an IRC bouncer / proxy and how does it work?
* Introducing ZNC
* Download, installing, and configuring ZNC on a Fedora machine
* Configuring IRC client to use your ZNC bouncer

8
modules/ROOT/pages/writing-an-article.adoc Normal file
View file

@ -0,0 +1,8 @@
= Writing an article for the Fedora Magazine
Now that you have an approved pitch, you can **write your article**. https://fedoramagazine.org/how-to-structure-your-article/[Here’s a template you can use] to structure your article well, and make it as useful as possible to readers. Make sure you set the article status from Pitch to Draft once you receive approval.
As you write your draft, try to understand and follow the xref:tips-for-writers.adoc[style, grammar, and SEO guidelines] for the Magazine. Don’t skip this step! The guidelines tell you how to use markup, write better sentences, and get your article ranked well in search engines. Also, if you write a better article, the editors are more likely to publish it sooner.
When you’re completely finished, **submit the article for review**. Set your article’s Status as Pending review in the Publish box at top right, and email the mailing list. The editors will review your draft, and provide feedback to you via the mailing list. Please note that once you mark your article as Pending review the editors assume you believe the article is ready to publish.

14
nginx.conf Normal file
View file

@ -0,0 +1,14 @@
server {
listen 80;
server_name localhost;
location / {
root /antora/public;
index index.html index.htm;
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}

18
preview.sh Executable file
View file

@ -0,0 +1,18 @@
#!/bin/sh
if [ "$(uname)" == "Darwin" ]; then
# Running on macOS.
# Let's assume that the user has the Docker CE installed
# which doesn't require a root password.
echo "The preview will be available at http://localhost:8080/"
docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx
elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then
# Running on Linux.
# Fedora Workstation has python3 installed as a default, so using that
echo ""
echo "The preview is available at http://localhost:8080"
echo ""
cd ./public
python3 -m http.server 8080
fi

20
site.yml Normal file
View file

@ -0,0 +1,20 @@
site:
title: Fedora Magazine
start_page: fedora-magazine::index
content:
sources:
- url: .
branches: HEAD
ui:
bundle:
url: https://asamalik.fedorapeople.org/ui-bundle.zip
snapshot: true
default_layout: with_menu
output:
clean: true
dir: ./public
destinations:
- provider: archive
runtime:
pull: true
cache_dir: ./cache