Use Linux on the desktop or server? Want to benefit from writing user documentation? There’s no better way to wrap up 2023 than with the Fedora Docs workshop.
Join us on December 7, 2023 from UTC 08:00-09:00 (see local time below). The Fedora Docs team will guide you on how to contribute user documentation, get ahead of technical writing skills and learn Docs tool set.
Continue readingOn behalf of all of the folks working on Fedora licensing improvements, I have a few things to announce!
All documentation related to Fedora licensing has moved to a new section in Fedora Docs, which you can find at https://docs.fedoraproject.org/en-US/legal/. Other legal documentation will follow. This follows the overall Fedora goal of moving active user and contributor documentation away from the wiki.
The “good” (allowed) and “bad” (not-allowed) licenses for Fedora are now stored in a repository, using a simple structured file format for each license (it’s TOML). You can find this at https://gitlab.com/fedora/legal/fedora-license-data. This data is then presented in easy tabular format in the documentation, at https://docs.fedoraproject.org/en-US/legal/allowed-licenses/.
Historically, this information was listed in tables on the Fedora Wiki. This was hard to maintain and was not conducive to using the data in other ways. This format will enable automation for license validation and other similar process improvements.
We’re changing the policy for the “License” field in package spec files to use SPDX license identifiers. Historically, Fedora has represented licenses using short abbreviations specific to Fedora. In the meantime, SPDX license identifiers have emerged as a standard, and other projects, vendors, and developers have started using them. Adopting SPDX license identifiers provides greater accuracy as to what license applies, and will make it easier for us to collaborate with other projects.
Fedora licensing policies and processes have been updated to reflect the above changes. In some cases, this forced deeper thought as to how these things are decided and why, which led to various discussion on Fedora mailing lists. In other cases, it prompted better articulation of guidance that was implicitly understood but not necessarily explicitly stated.
Many software packages consist of code with different free and open source licenses. Previous practice often involved “simplification” of the package license field when the packager believed that one license subsumed the other — for example, using just “GPL” when the source code includes parts licensed under a BSD-style license as well. Going forward, packagers and reviewers should not make this kind of analysis, and rather use (for example) “GPL-2.0-or-later AND MIT”. This approach is easier for packagers to apply in a consistent way.
The resulting changes in practice will be applied to new packages and licenses going forward. It is not necessary to revise existing packages at this time, although we have provided some guidance for package maintainers who want to get started. We’re in the process of planning a path for updating existing packages at a larger scale — stay tuned for more on that!
A huge thanks to some key people who have worked tirelessly to make this happen: David Cantrell, Richard Fontana, Jilayne Lovejoy, Miroslav Suchý. Behind the scenes support was also provided by David Levine, Bryan Sutula, and Beatriz Couto. Thank you as well for the valuable feedback from Fedora community members in various Fedora forums.
Please have a look at the updated information. If you have questions, please post them to the Fedora Legal mailing list: https://lists.fedoraproject.org/archives/list/legal@lists.fedoraproject.org/
In a recent Fedora Magazine article we shared about a new burst of energy regarding the Fedora docs. We already implemented various improvements and worked on a plan to generally improve and update Fedora documentation.
The latter will lead to far-reaching changes in Fedora documentation and is about to happen now and entail continuous changes over the next approximately 12 months. We present here our analysis, our content concept and our implementation planning. We hope for ideas from the community to further enhance the concept and for support to turn it into reality.
Continue readingThe Fedora Docs team is starting the process of moving repos from the fedora-docs namespace on Pagure to GitLab. We’re making this move in order to take advantage of features like improved in-browser editing and cross-repo kanban boards. This move will be entirely transparent to the docs published at docs.fedoraproject.org. However, if you are contributing to one of the repos in this namespace, you’ll need to update the git remote.
Continue readingWe learned this week of the passing of John McDonough (jjmcd). John was a long-time contributor to the Fedora Project, and we are sad to hear of his passing. John contributed heavily to the Documentation team, sharing his knowledge with a global user community. John didn’t just write documentation, he also mentored new contributors. He was a patient and caring mentor, and our community is worse for his loss.
When I first became a Fedora contributor 11 years ago, John was one of the people who welcomed me into the Docs team. His guidance helped me become a better contributor. Although he stepped back from contributing a few years ago, his impact continues.
John’s passion for open source was matched by his passion for amateur radio. His contributions to our Amateur Radio Guide helped many hams get the most out of their hobby. WB8RCR, WB8RCR, WB8RCR, SK
I created a memorial page on the wiki. I invite your contributions.
Last week Jean-Baptiste Holcroft and Adam Šamalík met in Strasbourg for Docs Translations mini-FAD in order to prototype translations support for the Fedora Docs website. And we did a lot of work! This post is a report from the event, a status report, and a brief plan for how to move forward.
Our goal was to make sure we’re both on the same page about how it’s all going to work, to do some coding and publish a functional prototype, and to write a set of requirements for a potential production deployment.
The event happened a co-working space Le Shadok and we were grateful for being able to use the spaces for free.
Continue readingQuick docs are meant to be short articles on the official Fedora documentation site that cover commonly used workflows/tools.
Unlike wiki pages which are generally unreviewed, information on quick-docs follows the PR (peer-review + pull request) process. So the new information that is added there is more trustworthy and should be too, given that quick docs is listed on the official Fedora documentation website.
Fedora Internet of Things is a variant of Fedora focused on IoT ecosystems. This month I had the opportunity to focus on the Fedora IoT Documentation with the working group as a part advancing their objectives.
I began by expanding the “Getting Started” section to help people do as the title indicates: get started. This section is focused on getting the images downloaded and a device up and running with an initial user. The steps are detailed enough to help those that are also new to Fedora distributions.
Next I reorganized some of the remaining initial content into a “User Guide” section. This section covers topics thought of as the “next steps” in using the Fedora IoT images. I detailed the steps for managing updates with rpm-ostree and switching between development and stable builds. I also added examples for layered packages, adding repositories, and even running containers. Finally I provided some pointers for other administration tasks with links to existing Fedora Documentation.
Design ideas: My focus was on technical content. The basic layout is dictated by the Fedora Docs project but a bit of design work on the welcome page and the addition of any IoT specific logos would be nice. Also, there are a few screenshots that could use a pointer or box to highlight the area described in the text.
Verify links for downloads and upgrades: The working group now has regular updated images available in a CDN and the next downloadable image is in progress along with the final version of the landing page for downloads. Once the update and release schedule process is smoothed out, the documentation needs to be verified.
Get ready for F30: When Fedora 30 is ready, the site will need some Release Notes and the User Guide will need some updates to cover new features. You can submit suggestions as iot-docs issues in pagure.
A lot of progress was made this month and I learned more about asciidoc, ostree, and my Pi device. Also that my fingers are too big for microSD cards!
Check out the content at https://docs.fedoraproject.org/en-US/iot/
Feedback is welcome — just let us know with an iot-docs issue or through any of the methods mentioned on the welcome page!
This week, the Fedora Badges team published a full walk-through of how to design new Fedora Badges on the Fedora Docs site. The walk-through is the best reference to use when designing new badges. It includes the following:
If I had to choose one buzzword for Flock 2017 at Cape Cod, it would be ‘modularity’. Modules, module building, module testing, and module explaining seemed to be all over the place. I attended to give a workshop (with Aneta ŠP) about a proposed way to inject new life into the Fedora Documentation Project. Continue reading
Copyright © 2024 Fedora Community Blog
This work is licensed under a Creative Commons Attribution 4.0 International License.
Theme by Anders Noren — Up ↑
Recent Comments