#78 GSoD 2020 ideas
Closed 3 years ago by pbokoc. Opened 4 years ago by pbokoc.

Here's my proposal for the Install Guide for GSoD 2020:

Update and refactor the Fedora Installation Guide

The current Fedora Installation Guide (https://docs.fedoraproject.org/en-US/fedora/f32/install-guide/), while adequate, has been converted from a different publishing toolchain a few years ago and never updated to take advantage of the new, modular toolchain, Antora, that the Fedora Documentation Project currently uses. Additionally, parts of the Installation Guide are also being used inside the graphical installer to provide built-in help, however, at present time the installer is forced to use old, pre-conversion sources.

We would like to fix all issues described above. A writer working on this project would be expected to:

  • Modularize the guide so that it functions as a set of standalone modules and leverages the advantages of Antora, instead of the current hierarchical structure. This involves restructing the source file structure and updating all internal references (xrefs).

  • Work with the installer development team to ensure that the Installation Guide can be used as sources for the installer built-in help. People both in the Fedora Documentation Project as well as in the installer development team have prior experience with doing this and will be able to provide help.

The Installation Guide is written using the ASCIIDoc markup language (http://asciidoc.org/). Sources are store in git, and they are published using Antora (https://antora.org/). Familiarity with any of these tools, as well as basic scripting, is preferred but not necessary.
~~~

About the rest of the ideas

  • Let's delete "Update and republish our old Network Guide", "Consolidate and update the various Documentation Contributor Guides", the former is kind of a stretch goal and the latter is no longer relevant, we now have much better contributor docs.

  • I'm torn on "Review, update and add new Quick Docs", we should probably get rid of that too since there's a decent amount of contributions there regardless, and it's not very exciting.

  • "Update and enhance current contributor documentation, including developing ASCIIDoc markup guidelines and providing a set of ASCIIDoc snippets for common text editors (Atom, Vim, Emacs, Gedit)." - let's remove that too; I don't think having someone from outside the project developing guidelines is a great idea, and the snippets part would be cool, but it depends on the guidelines.

  • "Create a documentation set aimed at users completely new to Linux and Fedora" - I do like this one and we've been needing something like this for a while; I'll expand on the proposal and give you a better one in a subsequent comment.

That's it for the current proposals listed on the page. @sumantrom, how was the meeting with the networkmanager people, can they put together a proposal of their own?


Here's my proposal for the Install Guide for GSoD 2020:

Thanks for coming up with this.

Update and refactor the Fedora Installation Guide
The current Fedora Installation Guide (https://docs.fedoraproject.org/en-US/fedora/f32/install-guide/), while adequate, has been converted from a different publishing toolchain a few years ago and never updated to take advantage of the new, modular toolchain, Antora, that the Fedora Documentation Project currently uses. Additionally, parts of the Installation Guide are also being used inside the graphical installer to provide built-in help, however, at present time the installer is forced to use old, pre-conversion sources.
We would like to fix all issues described above. A writer working on this project would be expected to:

Modularize the guide so that it functions as a set of standalone modules and leverages the advantages of Antora, instead of the current hierarchical structure. This involves restructing the source file structure and updating all internal references (xrefs).

Work with the installer development team to ensure that the Installation Guide can be used as sources for the installer built-in help. People both in the Fedora Documentation Project as well as in the installer development team have prior experience with doing this and will be able to provide help.

The Installation Guide is written using the ASCIIDoc markup language (http://asciidoc.org/). Sources are store in git, and they are published using Antora (https://antora.org/). Familiarity with any of these tools, as well as basic scripting, is preferred but not necessary.
~~~

I like the idea and I will update the ideas page first thing tomorrow.

About the rest of the ideas

Let's delete "Update and republish our old Network Guide", "Consolidate and update the various Documentation Contributor Guides", the former is kind of a stretch goal and the latter is no longer relevant, we now have much better contributor docs.

+1 . i share the same thoughts

I'm torn on "Review, update and add new Quick Docs", we should probably get rid of that too since there's a decent amount of contributions there regardless, and it's not very exciting.

+1, however, i would like the first timers to still come and send a few PRs to get accustomed with Pagure and how things work.

"Update and enhance current contributor documentation, including developing ASCIIDoc markup guidelines and providing a set of ASCIIDoc snippets for common text editors (Atom, Vim, Emacs, Gedit)." - let's remove that too; I don't think having someone from outside the project developing guidelines is a great idea, and the snippets part would be cool, but it depends on the guidelines.

+1 to removing this

"Create a documentation set aimed at users completely new to Linux and Fedora" - I do like this one and we've been needing something like this for a while; I'll expand on the proposal and give you a better one in a subsequent comment.

This is exciting and a more elaborate one of this will be helpful.

That's it for the current proposals listed on the page. @sumantrom, how was the meeting with the networkmanager people, can they put together a proposal of their own?

The networkmanager and nmstate both have some proposals and we met. We have discussed expectations, I am going to finish structuring the final proposal tomorrow morning and update the ideas page.

@pbokoc can you point me out to the IRC channels you are mostly available on (if any) ?

@sumantrom Sure, I'm in #fedora-docs on FreeNode.

@sumantrom Here's a bit better proposal for the newcomer showcase docs:

Develop a set of documentation showcasing Fedora's features

Fedora Documentation is missing a set of docs aimed at people considering switching to Linux and Fedora in particular from other operating systems, notably MS Windows. We would like to create documentation that showcases Fedora's features relevant to a home user's general use cases, such as web browsing, multimedia creation and editing, video playback, working with documents and spreadsheets, and so on.

A writer working on creating such a doc set would be expected to work with various stakeholders in the Fedora Project such as the Mindshare Committee and project leadership, identify personas and their specific use cases, and then create documentation covering these use cases.

The documentation would be written using the ASCIIDoc markup language (http://asciidoc.org/), with sources stored in git and published using Antora (https://antora.org/). Familiarity with any of these tools is preferred but not necessary.

@pbokoc sounds like a good idea, I will update the current page right away

Metadata Update from @sumantrom:
- Issue assigned to sumantrom
- Issue tagged with: GSoD

4 years ago

I suppose we can close this now.

Metadata Update from @pbokoc:
- Issue status updated to: Closed (was: Open)

3 years ago

Login to comment on this ticket.

Metadata