A Proof of Concept (PoC) plan for new content proposal

pboy · March 30, 2022, 6:34pm

General basis: change as little as possible on the home page and not jeopardize the design.

Visual Structure:

keep with the max 3 box in a row structure
in the upper row:
- join the to leftmost boxes into one box: Fedora Linux (The larger width is for emphasis and is a substitute for heading)
- Informational text: Overview and guide to the user documentation (in a more cute wording)
- Inside basically keep the content, but replace Installation Guide by a text, saying Fedora has editions, each edtions differs somewhat in installation and where for find Information how to install the various edition. Remove System Admin Guide here.
- Keep Quick Docs where it is
Keep the next two rows.
Add to the light blue line a box: Fedora Tools Reference Guides.

ToC “Anaconda Reference Guide”

Introduction / Overview (for file based deployment, graphical Interface most used, alternative options remove VNC, Kickstart, text)
Quick tour graphical installation (new) (replaces/modifies current “Introduction”
a. Preparing Media
b. Step by step illustration of a typical process (With notes on which points are relevant differently for different editions)
Installation options (adjusted: Current section advanced Installation options
Current technical appendix: Kickstart Refence (LVM goes into a separate Guide, disk partioning to editions)

Issue

We are missing user doc für Workstation edition
- Workstation WG seems to discuss about documentation.
- Alternatively we could (I could) offer to edit parts of the current Installation guide into a (provisional/temporary) Workstation installation guide, until Workstation WG produces it’s new guide. Makes the situation for workstation probably not better, but at least not worst.
If we need an additional Workstation box:
- Add Workstation to the 2. row (saying Fedora Server. Fedora Workstation, Fedora IoT)
- Move Silverblue into the 3rd row replacing Epel
- Move Epel one row down replacing “Older releases” ( that should vanish anyway).

pboy · March 31, 2022, 5:58am

I’m just pondering my work plan for the upcoming week and wondering, how to proceed exactly with the content work here.

I can clone the Installation Guide repo, but I can’t work in the stg branch because it would change the current stg pages, what we don’t want. I could create another branch, but I wouldn’t be able to preview anywhere but locally. And in the long run it would be a mislabeled repo because it would no longer be an installation guide, but an Anaconda Reference Manual.

And unlike yesterday, I now think we should make the proposed changes in stg as soon as possible. Only in this way we will get a realistic preview. And the changes are not so big that everything would be turned upside down. We make changes of this kind practically on a regular basis.

And especially with regard to Outreachy applicants: they need as realistic a picture as possible of what we want in the future.

Where can we discuss the course of action further?

darknao · March 31, 2022, 7:53am

You can work on the same branch, but create another module. It’ll show up on stg (and prod since this repo doesn’t have a dedicated stg branch) but you’ll keep the current version alongside the new one you are working on.
Would that work for you?

pboy · March 31, 2022, 9:06am

I think so, yes. I have to create a new subdir, e.g. anaconda-reference-manual in parallel to the existing subdir install-guide? So I would have
~/modules/install-guide
~/modules/anaconda-reference-manual ?

And where will I find the latter?

If this is also visible on the prod page, it’s a tad nasty, but perhaps the least of the problems.

Thanks
Peter

darknao · March 31, 2022, 10:13am

Yes, exactly.
You can access it by entering the url manually, or you can add it to the nav menu on the left.
For that, you’ll need to create your own nav.adoc in modules/anaconda-reference-manual, then reference it in the main fedora user doc repository :

nav:
- modules/release-notes/nav.adoc
- modules/install-guide/nav.adoc
- modules/anaconda-reference-manual/nav.adoc
- modules/system-administrators-guide/nav.adoc

The master branch is for rawhide, so your work-in-progress module will only be visible on this version.

pboy · April 12, 2022, 10:12am

@darknao I still struggle with technical issues:

(a) Building the preview I get a lot of error messages like

ERROR (asciidoctor): target of include not found: partial$/entities.adoc
file: /antora/modules/workstation-install-guide/pages/index.adoc:2
source: /antora (refname: master )
ERROR (asciidoctor): target of include not found: partial$/entities.adoc
file: /antora/modules/getting-started/pages/downloading-fedora.adoc:2
source: /antora (refname: master )

WARN (asciidoctor): skipping reference to missing attribute: prodver
file: /antora/modules/anaconda-reference-guide/pages/index.adoc
source: /antora (refname: master )

ERROR (asciidoctor): level 0 sections can only be used when doctype is book
file: /antora/modules/workstation-install-guide/pages/index.adoc:5
source: /antora (refname: master )

I think I can just ignore those for now.

My biggest issue: I don’t get the navigation for my new content. There is always the same nay from Installation Guide. I suppose I missed or didn’t understand one of your hints.

The current content structure is:

modules
- anaconda-reference-guide
  - assets
  - pages
  - nav.adoc
- getting-started
  - assets
  - pages
  - nav.doc
- install-guide
  - assets
  - pages
  - nav.doc
- workstation-install-guide
  - assets
  - pages
  - nav.doc

For all my “new” pages I get the same nav.adoc from install-guide

That’s pretty much a hindrance for me right now. I tried it with start_path in site.yml, but no luck.

darknao · April 12, 2022, 6:26pm

I think I’ll need to see the current state of your repository to answer that, or at least the playbook (site.yml) you’re using.
For the fedora component, the navigation content is defined in the release-docs-home repository, inside the antora.yml file.
This file contains links to nav.adoc from all modules that is part of this same component.
Which means you should include at least this repository in your site.yml. You should use a local copy of it so you can include your own nav.adoc in the antora.yml file.
Does that make sense?

pboy · April 12, 2022, 8:42pm

It sounds very sensible, but not necessarily practical for me to implement.

My origin site.yml was:

site:
  title: Local Preview
  start_page: fedora:install-guide:index.adoc
content:
  sources:
   - url: .
     branches: HEAD
   - url: https://pagure.io/fedora-docs/release-docs-home.git
     branches: master
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:
  fetch: true
  cache_dir: ./cachetype or paste code here

That is quite standard. I hat to change it to be able to address the new anaconda-reference-guide
into

site:
  title: Local Preview
  start_page: fedora:anaconda-reference-guide:index.adoc
content:
...
...

As I read it I have to do now:

Clone Overview - fedora-docs/release-docs-home - Pagure.io and store is in its own subdirectory on my homedir, e.g. ~/Fedora-docs-home. The install guide is in a subdirectoy ~/Fedora-installation-guide.
I must modify the ~/Fedora-installation-guide/antora.yml to include somehow the local copy in ~/Fedora-docs-home, but how?
I must add my new docs to ~/Fedora-docs-home/antorra.yml something like

- modules/anaconda-reference-guide/nav.adoc
- modules/getting-started/nav.adoc
- modules/workstation-installation(nav.adoc

I hope I didn’t got it completely wrong.

darknao · April 12, 2022, 9:24pm

What I would do is something like this:
Inside your install-guide local repository, clone the release-docs-home repo.
You’ll end up with this folder tree:

install-guide
├── antora.yml
├── modules
│   ├── install-guide
│   │   ├── nav.adoc
│   │   └── pages
│   └── anaconda-reference-guide
│       ├── nav.adoc
│       └── pages
├── release-docs-home
│   ├── antora.yml
│   └── modules
└── site.yml

And in your site.yml playbook:

site:
  title: Local Preview
  start_page: fedora:install-guide:index
content:
  sources:
  - url: release-docs-home
    branches: HEAD
  - url: .
    branches: HEAD
  - url: https://pagure.io/fedora-docs/system-administrators-guide.git
    branches: master
  - url: https://pagure.io/fedora-docs/release-notes.git
    branches: master

You can then modify ./release-docs-home/antora.yml to add your anaconda nav.adoc in it.
That should do the trick.

pboy · April 12, 2022, 9:39pm

Thanks! I’ll try that tomorrow (it’s midnight here in Europe and time to shutdown the desktop).

pboy · April 19, 2022, 11:13pm

@darknao It works. Build and Preview generate a lot of error messages that I ignored as long as I could edit what I wanted.

I now have a very first draft ready. It is a rough arrangement and structuring of the contents of the Anaconda Reference Guide. The wording is all still raw and unedited, and also incomplete. Almost everything is sure to change.

I also collected some ideas for a Getting Started and put some things “aside” for a Workstation Installation guide, in case there is a need for it. But everything is still “more incomplete than incomplete”.

Do you want me to upload this so that you can add it to stg, or do you want to wait until things are more advanced? If it becomes available now, a possible advantage would be that others could comment and contribute ideas at a very very early stage. On the other hand, it is perhaps still too immature and too many things still only in my head, as that others could do something useful with it. I need another couple of hours to make everything clear. I am unsure. In any case, it is not yet ready for a wider audience.

Topic		Replies	Views
Project: New curation of the docs pages Project Discussion docs-team	0	186	June 13, 2022
Proposal of an umbrella plan for content Project Discussion docs-team	3	485	March 1, 2022
Docs meeting agenda: 2022-09-14 Project Discussion docs-team	7	319	September 14, 2022
New Documentation Homepage needs review and help Project Discussion docs-team	19	697	October 28, 2022
Content plan office hours Project Discussion docs-team	13	518	May 28, 2022

A Proof of Concept (PoC) plan for new content proposal

Related topics