#756 Use new overview adoc as source for mini-page to go on front of https://fedoraproject.org
Opened 2 years ago by mattdm. Modified 2 years ago

Right now, https://fedoraproject.org/ redirects to https://getfedora.org/. This was always meant to be temporary until we could get Fedora Hubs up and going. I still expect that's what we'll do, but in the meantime, the audience for getfedora.org — that is, people looking to get the Fedora OS right now — isn't the same as for the project website overall.

We have new Fedora Project Overview documentation at https://docs.fedoraproject.org/fedora-project/project/fedora-overview.html. I had initially proposed redirecting to this, but based on comments, the new proposal is to render https://pagure.io/Fedora-Council/council-docs/blob/master/f/project/fedora-overview.adoc to HTML and use that as the core of a new, simple site to just be that front page.


Update: docs are now live

@mattdm if that redirect was set up as-is I think we'll have a lot of confusion about which is the 'real' fedora website, and if one is meant to place the other.

I suggest changing the title on the docs docs one to say something like "Fedora Project Community" instead of just "Fedora" so it was clear what it specifically is.

The logo sizing on that page is out-of-proportion with the layout / text size, is there a way to modify that?

@mattdm if that redirect was set up as-is I think we'll have a lot of confusion about which is the 'real' fedora website, and if one is meant to place the other.

I think we have that confusion already....

I suggest changing the title on the docs docs one to say something like "Fedora Project Community" instead of just "Fedora" so it was clear what it specifically is.

The HTML title, or the header, or something else?

The logo sizing on that page is out-of-proportion with the layout / text size, is there a way to modify that?

Yes. See https://pagure.io/design/issue/552

@mattdm that ticket says "though note that improvement to the overall look of the docs site (including styles, fonts, etc.) are out of scope and a separate design project." I don't understand. Does that mean the CSS can't be fixed?

We can adjust the CSS, but that's part of a bigger thing because it would affect all of https://docs.fedoraproject.org/. I don't think we want to do per-document CSS.

But, we can adjust the logo which is part of the document.

What is generating docs.fedoraproject.org? It's not using Fedora bootstrap? Who created this theme?

I have no strong opinion where fedoraproject.org should redirect to, but I think people who went to fedoraproject.org were not looking for docs. The docs.fp.o will confuse people more than getting redirected to getfedora.org. Also:

  • I see docs.fp.o still a website with a lot of work in progress (links changed, CSS has to be fixed, the website is only partially mobile-friendly, no responsive tags for images, etc)
  • Why should we redirect to a sort of overview with just Council links? Seems to me like redirecting to a smaller wiki page. FInally, are users who are looking for Fedora, searching informations about the Council?

Btw, can anyone tell me why the images on the docs pages have soooooooo long paths?
@duffy no, it seems it is using :

<!-- Bootstrap --> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css"> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap-theme.min.css">

I see docs.fp.o still a website with a lot of work in progress (links changed, CSS has to be fixed, the website is only partially mobile-friendly, no responsive tags for images, etc)

There's definitely room for improvement.

Why should we redirect to a sort of overview with just Council links? Seems to me like redirecting to a smaller wiki page. FInally, are users who are looking for Fedora, searching informations about the Council?

I'm not sure I understand. I'm suggesting redirecting to https://docs.fedoraproject.org/fedora-project/project/fedora-overview.html. The Council docs are findable on the left, but under a different section, starting with https://docs.fedoraproject.org/fedora-project/council/charter.html

Btw, can anyone tell me why the images on the docs pages have soooooooo long paths?

For whatever reason, asciibinder turns images into inline data. We'd have to ask the asciibinder authors about that.

@duffy no, it seems it is using :

<link rel="stylesheet" href="&lt;a href=" https:="" maxcdn.bootstrapcdn.com="" bootstrap="" 3.3.5="" css="" bootstrap.min.css&quot;"="">https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<link rel="stylesheet" href="&lt;a href=" https:="" maxcdn.bootstrapcdn.com="" bootstrap="" 3.3.5="" css="" bootstrap-theme.min.css&quot;"="">https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap-theme.min.css">

This comes from upstream asciibinder. I tried dropping in the Fedora bootstrap fork, but it caused a lot of problems (images misaligned, the whole thing being undifferentiated gray, etc.). @bex is talking to @ryanlerch about possibly using Fedora's bootstrap instead of the upstream one, but there would need to be some tweaks.

Can you please wait to have multi-language support for documentation?
While we can debate the getfedora landing is or isn't the best place to arrive (I have no idea), at least non English speaker can understand something.

@jibecfed That's definitely worth taking into consideration. I think we could do multi-language more quickly for just this one page rather than waiting for a full docs solution, especially if we go with @duffy's suggestion of re-publishing the content in a different format for the front page.

Right now, we have asciibinder to translate the asciidoc file into html for the docs site. But we could just run asciidoctor directly (as asciidoctor -s to create "bare" HTML which could be inserted into whatever workflow works for the websites team.

@bex , does that seem like a reasonable idea? We could simply add a "translations" subdirectory to council-docs/project/, and then different language subdirectories under there? Or we could even have a separate repo for translated versions of this one document.

Then, when we get the full docs translation workflow up and going, we could regularize this with that.

I think we are close to have something that works fine for internationalization. The main question is about how to handle _topic_map.yml . See https://pad.lqdn.fr/p/fedora-docs-internationalization-jibecfed
Is there any rush not to wait for a few days/weeks?
We already have passed the moment where we have a working documentation system, for which we had an agreement to focus on English only. By principle, I don't feel comfortable about removing the few localized content we have.

@jibecfed That's definitely worth taking into consideration. I think we could do multi-language more quickly for just this one page rather than waiting for a full docs solution, especially if we go with @duffy's suggestion of re-publishing the content in a different format for the front page.

Not sure I followed @duffy's solution here. Can someone rephrase it?

I am -1 for hacked multi-language as we are pretty close. I am cool with a deadline though.

Right now, we have asciibinder to translate the asciidoc file into html for the docs site. But we could just run asciidoctor directly (as asciidoctor -s to create "bare" HTML which could be inserted into whatever workflow works for the websites team.

@bex , does that seem like a reasonable idea? We could simply add a "translations" subdirectory to council-docs/project/, and then different language subdirectories under there? Or we could even have a separate repo for translated versions of this one document.
Then, when we get the full docs translation workflow up and going, we could regularize this with that.

I updated the issue above with a new proposal.

I'm not sure where translation fits into this or how it interacts with docs.fpo proposal — note that _topic_map.yml doesn't even come into it.

@jibecfed Note that I'm not suggesting getting rid of getfedora.org at all. Just to stop redirecting fedoraproject.org's top level to it. (I feel like it's really confusing when the top page of a site redirects to a whole different site, but there's still content under the first one — in this case, prominently, all the wiki content.)

curl -s https://pagure.io/Fedora-Council/council-docs/raw/master/f/project/fedora-overview.adoc|asciidoctor -

I updated the issue above with a new proposal.
I'm not sure where translation fits into this or how it interacts with docs.fpo proposal — note that _topic_map.yml doesn't even come into it.

The topic map has been a translation blocker. This may now be fixed.

curl -s https://pagure.io/Fedora-Council/council-docs/raw/master/f/project/fedora-overview.adoc|asciidoctor -

Does this mean your proposing just this page’s content be located on a separate site. Then something like this in cron would keep it current?

Does this mean your proposing just this page’s content be located on a separate site. Then something like this in cron would keep it current?

Yeah, cron, or, as some kind of CI/CD pipeline. It'd take the adoc, run asciidoctor -s (the -s suppresses the built-in header and footer) and put it in the middle of some custom header and footer for the mini-site.

@jibecfed Note that I'm not suggesting getting rid of getfedora.org at all. Just to stop redirecting fedoraproject.org's top level to it. (I feel like it's really confusing when the top page of a site redirects to a whole different site, but there's still content under the first one — in this case, prominently, all the wiki content.)

I understand it and totally agree with you. I'll test yaml import tomorrow so we can finish internationalization for docs.

Does this mean your proposing just this page’s content be located on a separate site. Then something like this in cron would keep it current?

Yeah, cron, or, as some kind of CI/CD pipeline. It'd take the adoc, run asciidoctor -s (the -s suppresses the built-in header and footer) and put it in the middle of some custom header and footer for the mini-site.

I am +1 this and will work with Web to determine the best place for it to live. It sounds like it will need the translation toolset from docs but a hosting site like web. I have some ideas ...

However, what we need to get going for realz is the header/footer from design.

Login to comment on this ticket.

Metadata