design/docs
16
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

First update

Browse source
This commit is contained in:
emma kidney 2025-02-13 16:37:45 +00:00
commit 88bb83fb50
6 changed files with 129 additions and 143 deletions
Download patch file Download diff file Expand all files Collapse all files

137
README.md
View file

@ -1,126 +1,51 @@
# Fedora Design Docs
Fedora Design Team documentation
===================================
## Structure
This repository contains the source content for the [Fedora Design Team documentation][1].
The Antora configuration files and AsciiDoc source content are hosted in this repository.
Please report Issues and submit Merge Requests for **content fixes** here.
```
|-- README.md
|-- antora.yml ....................... 1.
|-- docsbuilder.sh ................... 2.
|-- site.yml ......................... 3.
`-- modules
`-- ROOT ......................... 4.
|-- assets
| `-- images ............... 5.
| `-- pizza.png
|-- nav.adoc ................. 6.
`-- pages .................... 7.
|-- architecture.adoc
|-- community.adoc
|-- faq.adoc
|-- index.adoc
|-- pizza-dough.adoc
`-- pizza-oven.adoc
```
1. Metadata definition.
2. A script that does a local build. It shows a preview of the site in a web browser by running a local web server. Uses podman or Docker.
3. A definition file for the build script.
4. A "root module of this documentation component". Please read below for an explanation.
5. **Images** to be used on any page.
6. **Menu definition.** Also defines the hierarchy of all the pages.
7. **Pages with the actual content.** They can be also organised into subdirectories if desired.
## Contributing
## Components and Modules
The contents of this repository are licensed under the default content license of the Fedora Project.
Contributions are accepted under the default content license of the Fedora Project unless explicitly stated otherwise.
Contributors to this repository must have signed the [Fedora Project Contributor Agreement](https://docs.fedoraproject.org/en-US/legal/fpca/).
Antora introduces two new terms:
* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Project, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modularity.
* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
## Report an issue with the Design Team docs
Noticed some wrong or incorrect with the Design Team documentation?
Open a new Issue to report the problem.
Check the list of open issues first to see if someone else has already reported the problem before opening a new issue.
[**Fedora Design Team docs issues**][2]
## Local preview
This repo includes a script to build and preview the contents of this repository.
**NOTE**: Please note that if you reference pages from other repositories, 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.
This repo includes scripts to build and preview the contents of this repository.
Both scripts work on Fedora (using Podman) and macOS (using Docker).
To build and preview the site, run the following commands in a terminal:
To build and preview the site, run:
```
$ ./docsbuilder.sh -p
```sh
cd /path/to/fedora/design/docs/
./docsbuilder.sh -p
```
The result will be available at http://localhost:8080
A preview of local changes will be available at [localhost:8080](http://localhost:8080).
To stop the preview:
```
$ ./docsbuilder.sh -k
```
**NOTE**: If you `xref` to pages from other repositories, those links will not work 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][3] for instructions.
### 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:
You may need to install Podman using the following command on Fedora Linux:
```
$ sudo dnf install podman
```sh
sudo dnf install podman
```
### Preview as a part of the whole Fedora Docs site
You can also build the whole Fedora Docs site locally to see your changes in the whole context.
This is especially useful for checking if your `xref` links work properly.
To do this, you need to clone the main [Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o), modify the `site.yml` file to reference a repo with your changes, and build it.
Steps:
Clone the main repository and cd into it:
```
$ git clone https://pagure.io/fedora-docs/docs-fp-o.git
$ cd docs-fp-o
```
Find a reference to the repository you're changing in the `site.yml` file, and change it so it points to your change.
So for example, if I made a modification to the Modularity docs, I would find:
```
...
- url: https://pagure.io/fedora-docs/modularity.git
branches:
- master
...
```
And replaced it with a pointer to my fork:
```
...
- url: https://pagure.io/forks/asamalik/fedora-docs/modularity.git
branches:
- master
...
```
I could also point to a local repository, using `HEAD` as a branch to preview the what's changed without the need of making a commit.
**Note:** I would need to move the repository under the `docs-fp-o` directory, because the builder won't see anything above.
So I would need to create a `repositories` directory in `docs-fp-o` and copy my repository into it.
```
...
- url: ./repositories/modularity
branches:
- HEAD
...
```
To build the whole site, I would run the following in the `docs-fp-o` directory.
```
$ ./docsbuilder.sh -p
```
# License
SPDX-License-Identifier: CC-BY-SA-4.0
[1]: https://docs.fedoraproject.org/en-US/design/
[2]: https://gitlab.com/fedora/design/team/docs/-/issues
[3]: https://gitlab.com/fedora/docs/docs-website/docs-fp-o

3
modules/ROOT/nav.adoc
View file

@ -0,0 +1,3 @@
* xref:get-involved.adoc[Get Involved]
* xref:resources.adoc[Resources]
* xref:help.adoc[Need Design Help?]

33
modules/ROOT/pages/get-involved.adoc Normal file
View file

@ -0,0 +1,33 @@
include::ROOT:partial$attributes.adoc[]
= How do I get involved?
== Getting Started
1. Join the Element Fedora Design https://matrix.to/#/#design:fedoraproject.org[group chat].
2. Introduce yourself to the group; talk about your art/design experience and interests so we'll know what kinds of design tasks you might be interested in helping out with.
3. Sign up for a https://docs.fedoraproject.org/en-US/fedora-accounts/user[Fedora Account], you'll need it later!
4. Complete the https://docs.fedoraproject.org/en-US/legal/fpca[Fedora Project Contributor Agreement] (FPCA) through the https://docs.fedoraproject.org/en-US/fedora-accounts/user[Account System]. This will ensure that the contributions you make are properly licensed!
5. Complete a small task to join the team. To find something to work on, you can do any of the following:
* Claim and complete a design ticket at the https://gitlab.com/fedora/design/team/requests/-/issues[Fedora Design Issue Request queue].
* Look at the https://gitlab.com/groups/fedora/design/team/-/issues[Fedora Design issues], and see if any are flagged for newbies!
* Ask the group in Element if there are any tickets that need attention.
Note: We definitely recommend for folks starting out with our team to look for tasks that are not icon-related. Icon designs pose additional burdens and challenges that we don't want you to have to deal with just starting out! The same applies to logos.
6. Once you've completed an initial draft of your design task, comment on the ticket, and pop the link or artwork in the https://matrix.to/#/#design:fedoraproject.org[Element design group chat] for feedback and approval.
7. Once your design is approved, send a message to the design team in Element requesting an invite to the design-team group. Provide your Fedora Account username so we can add you in.
After you have completed these steps, you can begin contributing to a project as a full member of the design team. Questions and suggestions may be asked within the ticket as well as the Fedora Design group chat on Element.
== Join our meetings!
Video meetings will be held every *Monday at 14:30 UTC* on https://meet.jit.si/FedoraDesign[*Jitsi*]. Please note that audio and video is not required to join the meeting - you can always use the chat for input if that is more comfortable for you.
Check the https://calendar.fedoraproject.org/design[Design Calendar] for updated meeting times. Meeting logs can be found at https://meetbot.fedoraproject.org/[meetbot.fedoraproject.org].
== Chat with us!
Design team members are present on the https://matrix.to/#/#design:fedoraproject.org[*#design:fedoraproject.org* Matrix room] on https://chat.fedoraproject.org/[chat.fedoraproject.org].
Feel free to reach us here!

15
modules/ROOT/pages/help.adoc Normal file
View file

@ -0,0 +1,15 @@
include::ROOT:partial$attributes.adoc[]
= Need Design Help?
== Filing an issue
You can file an https://gitlab.com/fedora/design/team/requests/-/issues/[issue] to:
* Request new design work
* Tell us if something's wrong with an existing design
* Make a suggestion for a future design
== Now what?
Because this is mainly a volunteer-staffed team, we don't guarantee to handle all tickets. If you think a ticket needs attention and would like to work on it, but someone else took ownership of the ticket: try to contact the owner and see if they are working on it. If you don't hear from them within a week you can probably take the ticket over. If you have a filed a ticket and have not heard from anyone, please feel free to https://matrix.to/#/#design:fedoraproject.org[join our chat] for attention / guidance / support.

53
modules/ROOT/pages/index.adoc
View file

@ -1,53 +1,30 @@
include::partial$attributes.adoc[]
include::ROOT:partial$attributes.adoc[]
= The Pizza Project
= Fedora Design
The Pizza Project is a useful project with a very bad name — it's just what's in our template repo to show off some basics.
== About Us
In fact, this is just a source template for a new piece of the Fedora Docs.
The Fedora Design Team is Fedora's in-house design agency. We provide artwork, user experience, usability, and general design services to the Fedora project.
Our current team goals:
Below is some hopefully useful info about how to work with this stuff.
== Antora & ASCIIDoc basics
* *Template and Automate* - Generate templates, standards, and automation where possible for more efficient and consistent artwork production.
* This whole section is a list, hence the points.
* Below is an image. The image source is located in `modules/ROOT/assets/images`. See the source for how it's inserted.
+
image::image$pizza.png[Pizza]
+
Notice that the image is a part of the same "list item" as the sentence above it; that's due to the `+` on newlines, if you delete that and refresh the page, it'll move slightly to the right. That's not really relevant to an unordered list like used here, but you'll need it if you want to make a numbered list with a multi-paragraph list item. The `+` sign joins multiple paragraphs (or other block elements like images or that "Tip" box below) into one item.
+
You can also make some changes to how images are displayed, like set width/height, scaling, alignment, even turn one into a link. See here for available attributes: link:https://docs.asciidoctor.org/asciidoc/latest/macros/image-ref/[ASCIIDoctor Docs]. These options are all, well, optional.
* *Increased focus on UX/usability* - Increase the amount of UX and usability work we provide to the Fedora project through both more efficient usage of current designer time and also better recruitment of UX/usability team members and better documentation of UX/usability tasks and processes.
* You can also add images inline (as part of a paragraph of text), but that's rarely useful. If you ever need to do that, just use one colon instead of two in the `image:` declaration and put it into a paragraph. It never looks good though.
* Last updated in {year}. Notice how in the page source, the sentence used the attribute `\{year}` instead of just saying 2022. The attribute is defined in `modules/ROOT/assets/partials/`, there is also an example file that explains this further. Don't forget to include the attributes file on top of the page if you want to use these.
* *FLOSS Creative Tool Education & Outreach* - Continue to use the very same free and open-source creative tools available in Fedora to design for Fedora, and increase and improve knowledge sharing with the general FLOSS community.
* To link to another page in the same repository, instead of using a hard `\link:<url>[<text>]` (used for outside links), use an `xref instead`. For example, to link to the Architecture page, use `\xref:architecture.adoc[Architecture]`, which results in this: xref:architecture.adoc[Architecture]. The navfile (`nav.adoc`) uses those as well, check it out and look how it works. (Also note how you can add multiple levels to the list). It's also possible to use this to link to another repo that's published on Docs.FP.O, but that gets more complicated. Ping me if you ever need to do that.
* Each page needs to start with a top level heading, preceded by `=` (like this one). Any subsequent headings then have a number of equals signs which determine their depth. These will automatically show up in a table of contents that's automatically generated on the right.
* *Clear Priorities* - Strive to be more selective about our focus as a team and set clear priorities so the things that are most important to Fedora are done in a timely and organized manner.
[TIP]
====
Other than that, you might find a [TIP] infobox like this useful. You can also use [CAUTION] and [WARNING] if you need to, they have different border (purple and red).
====
== Join Us
* Inserting a code block works like this:
+
[source]
----
$ dnf install podman -y
----
+
Optionally you can specify which language it's using to set the correct keyword highlighting; to do that, add a keyword specifying the language immediately after the "source" keyword. Like this: `[source,bash]` - I can't remember where the full list of keywords was, but if you ever need it, ping me and I'll try to dig it up.
We're always looking for new members. Join the design team and:
* Any new pages you write should go into the `modules/ROOT/pages` directory and have the `.adoc` file extension. Then, you also need to add the file to the `modules/ROOT/nav.adoc` file; if you don't, they will still exist, but they will only be accessible if you know their exact URL. Of course, deleting pages (like the weird stuff currently in the repo) works the same way, if you delete something, delete both the file and the entry in `nav.adoc`.
* Build your portfolio by working on real-world projects
* Learn open-source design tools from experts - never pay for Creative Suite again!
* Work with awesome designers from around the world
* The `modules/ROOT/pages` directory can have subdirectories, called topics. This may be useful if you find that there are multiple self-contained areas of docs with a lot of pages and you want to keep them separate so the repo is easier to work with. In that case, you can just make subdirectories in `pages/`, and when you're using an xref, add the topic subdirectory into the path (for example, `\xref:other_topic/page_name.adoc[A page in the other_topic directory]`). If the repo isn't too big it's easier to just not bother with subdirectories.
* Use the docsbuilder.sh script in the root of this repo to run a preview - just open a terminal, point it at the repo root, and run `./docsbuilder.sh`. You'll need to have `podman` and `inotify-tools` installed. If there's anything else you need, the script will tell you with an error message. The `README.md` in this repo explains how it works.
* Finally, for the actual writing: Here's our link:https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/[docs guide], go through the Writing Contributions to Docs, especially the link:https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/asciidoc-markup/[markup] section. A decent list of syntax for commonly used elements (lists, etc.) is in the link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[ASCIIDoc Syntax Quick Reference].
//Yes, I just used a hardlink to another docs repo instead of an xref. Also this is a comment, it won't be displayed on the page but you can use it for TODOs and such.
To learn how to join Fedora Design Team, please see the xref:getinvolved.adoc[Get Involved] page.

33
modules/ROOT/pages/resources.adoc Normal file
View file

@ -0,0 +1,33 @@
include::ROOT:partial$attributes.adoc[]
= Resources
Dedicated page to help you find assets, tutorials, and recommended software to support your work and contributions.
== Assets
* https://docs.fedoraproject.org/en-US/project/brand/#_the_fedora_logo[*Fedora Logo*] - Fedora logo information, including usage guidelines
* https://docs.fedoraproject.org/en-US/project/_attachments/brand-book-revised-2024.pdf[*Fedora Brand Book*] - Brand guidelines booklet in PDF format
* https://gitlab.com/fedora/design/team/event-kit/[*Event Kit*] - Design assets related to Fedora events (banners, tablecloth, etc.)
== Tutorials
* https://gitlab.com/fedora/design/team/tutorials/inkscape-automation[*Inkscape Automation*] - Tutorial for how to use Inkscape to automate the production of SVG, PNG, EPS, PS, or PDF graphics using a template file and CSV data input.
== Open-Source Design Software
* https://penpot.app/[*Penpot*] - web-based design and prototyping platform.
* https://inkscape.org/[*Inkscape*] - vector graphics editor
** https://opensource.com/sites/default/files/gated-content/cheat_sheet_inkscape.pdf[Inkscape cheat sheet]
* https://www.blender.org/[*Blender*] - 3D computer graphics software
** https://opensource.com/sites/default/files/gated-content/cheat_sheet_blender_v2.pdf[Blender cheat sheet]
* https://krita.org/en/[*Krita*] - digital painting application
** https://opensource.com/article/21/12/krita-digital-paint[Open source digital painting with Krita]
* https://www.gimp.org/[*GIMP*] - image editor
** https://www.gimp.org/[GIMP cheat sheet]
* https://kdenlive.org/en/[*Kdenlive*] - video editor
** https://opensource.com/sites/default/files/gated-content/osdc_cheatsheet-kdenlive-2021.12.3.pdf[Kdenlive cheat sheet]