Redesign Docs front page layout- Outreachy Project 2022 (Help required)

Hi @mattdm , I believe you’d be a better person to review an information architecture I prepared for the docs website since you have defined the terms in your blog and know best about them.

Here’s the Figma link: https://www.figma.com/file/7nsbTWEsQGZQQOLD8xg8Fd/Fedora?node-id=0%3A1 you can also see some major issues I found in the website which could be worked upon.

Suggestions are welcome!

3 Likes

Great work with many incentives @likeanushkaa ! Concerning your argument about the search engine, you are absolutely right: this is already in development. You can test it at Fedora Documentation :: Fedora Docs (this is yet just a test page; @darknao does some great work on that).

You can find the related discussion on

3 Likes

Hey, this is amazing. I do have some design suggestions, I’d add in the thread by eod today:)

I’m happy to see search in action!

2 Likes

I’m not Matthew, but I do have a few comments on the design.

Information architecture

  • I don’t think including the packaging guidelines under the “Fedora Linux” category is a good fit. It looks like most of the content you included under Fedora Linux is user-facing, but the packaging guidelines are primarily for contributors. (They’re useful as a reference for users who want to make their own packages, but that’s not the target audience)

Issues

  • “There is no way to get back to the main Fedora website…” So I’d argue there is no “main Fedora website”, which is perhaps another problem in itself. But I assume you mean getfedora.org. I agree that it would be good to have clear links to that site—and probably Ask Fedora¸ too—for people who want to get to downloads after reading docs.
  • “No introduction of topics to help a new user…” Agreed. Some of the questions that I’ve answered from Outreachy applicants—particularly around the different variants—have made it very clear that we’re not explaining things well to newcomers. I don’t know how much we could address that on the front page versus an explainer page clearly linked from the front page, but it’s definitely something we should keep in mind.
  • “The dropdown opens a list of topics different from the list of topics actually available on the landing page of the website”. That’s intentional, as each module provides its own navigation. That prevents the navigation column from being so full as to be entirely unusable. That said, many modules could use some additional curation so that the navigation makes sense and is somewhat consistent. I do think the user docs should more closely (but not exactly) reflect the front page.
  • Relatedly, how do you think we could make the navbar and breadcrumbs be less confusing? I do think they both serve different purposes, so we want them both and we don’t want them to be identical. But we do want them to be helpful.
  • “A lot of content is repetitive”. What’s the issue with the repetitive content? (Assuming they all pull from the same “source” so we don’t have to update 10 different places). The idea is that people shouldn’t have to jump to many different places to find out what they need. So if you’re looking at the Installation Guide or the Sysadmin Guide, you should still see the minimum hardware requirements, for example, because we don’t expect that you should have to read both.
2 Likes

We do still redirect fedoraproject.org to getgedora.org. Would not be fedoraproject.org the right place to catch up with introduction of the projects and all the topics of it?

Hi, @bcotton -

So should it be mentioned in the contribute category?

I have updated the same link: https://www.figma.com/file/7nsbTWEsQGZQQOLD8xg8Fd/Fedora?node-id=0%3A1 with thoughts around this ( under solutions, navigation 1&2)

WRT the solution I propose, since the user can now toggle easily between different articles, I wanted to point out that - for example for releases- inside Fedora Linux- a section about Hardware overview can be mentioned once, and release notes can be another section with f35, f34, f33, etc. as topics inside it. This way the user can visit the hardware overview from any release note.

There isn’t exactly a problem with repetition of content, but it’d make the docs website more organized if articles are mentioned once properly IMO. And we should explore ways of redirecting the user to that one page whenever they would require it.

Please review the files again, as I’ve updated more content!

This page might also be the point where people could be made aware of the docs, especially as some may start at this page when they seek help. But the docs are not even mentioned or indicated:

However, obvious links could be integrated into getfedora, both for docs and the intro.

Okay, I see what you mean. What I have in mind is more along the lines of having sections that get included into different docs, so instead of redirecting the user to the page they need, it’s in there as part of a “recipe” for the general thing they’re accomplishing. Of course, it’s not a purely one-or-the-other situation. There will need to be a mix of the two to varying degrees based on context.

I really like the layout of your proposal, in particular how you handle the nav bar.

You asked for guidance on where to bucket the Packaging Guidelines. Those are, essentially, documents for a particular type of contributor: package maintainers. To some degree, you can consider that an engineering team, although it’s really more of a classification of individuals than a cohesive team, if that makes sense. I pointed out in another submission that a “policies” bucket that includes links various guidelines, policies, etc might be a good way to improve discoverability (e.g. so that you don’t have to know that the Changes Policies are part of the Program Management docs). There’s probably not a great way to automate that, but a manually-curated set of links would be better than what we have now, which is nothing. :slight_smile:

Did I miss anything?

2 Likes

Hi! I think this is generally quite good! I just have a few small comments…

  • How do people feel about “contribute”? To me, it seems too one-sided. My first response is something like “Join Fedora!” or “Get Involved!”… but maybe those sound like they’re too big, too much of a commitment? Any ideas for something in between (or a way to provide two paths — one the big “Fedora is awesome come be our friend!!!” message [1] message, and another “hey, you just wanna make a little improvement without a fuss? no problem!” [2]

  • There will be a https://fedoraproject.org/ again with the new website design, which is in progress.

  • The Solutions → spins| labs bit could become just “Other Fedora Solutions”. And although I don’t think we want a high-level split, it is useful to call out the popular desktop-environment spins.


  1. imagine this one with, like, a big Labrador retriever :dog2: ↩︎

  2. Like a cat. Come and go mysteriously, and only make attachments if you are feeling in that particular mood at the moment. ↩︎

3 Likes

I think in the solutions, I’ve room to make sections in a particular doc; this could be done!

Thank you! Currently, I have two iterations in mind; I think some user testing might help finalize one solution.

I saw someone’s introduction and how they had contributed to the fedora using the guidelines. I think I’d then bucket these inside a new Policies tab.

I think not. The only thing is, what should I focus on next? Should it be more around building the next level of information architecture- since I’ve just categorized the main headings right now? Or should it be around finalizing the home screen page from the iterations I’ve made?

Thank you so much for the help:)

Get involved sounds good, IMO. Something related to community/ open-source might work?

  • Join the community
  • Volunteer Opportunities

That would be great, the point I raised was basically around having proper navigation between different fedora websites, so that a user can jump easily from one to another.

We could mention spins and labs with their definitions on the website.

I’m also curious to know- what would be shown on the main Fedora website, since everything bout Fedora is in the Docs, just want to understand the logic behind all of the different websites!

Thankyou so much for the help:)

2 posts were split to a new topic: Status of fedoraproject.org “front page”

At the risk of giving you a non-answer, whichever you think makes for a stronger proposal. :slight_smile:

Aha got it, maybe I can work around both!:sweat_smile::see_no_evil:

This is the current state of the global navigation design for across fedoraproject.org:

Currently it mirrors the structure of the site-wide footer design:

The docs website doesn’t have its own slot right now and the rationale is this: docs are contextual to the edition or community team or process they are linked to. Starting from docs.fpo, I see a lot of documentation where you could access it primarily from somewhere else - Fedora Silverblue’s documentation you’d access from the silverblue website, the Fedora Project “doc” in actuality probably is best utilized as the “About” page for fedoraproject.org and styled accordingly.

I do not see docs.fedoraproject.org being a destination so much as a street actual destinations happen to live on, if that makes sense? The range of content it covers is so too disparate IMHO.

I would say a good next step would be a little info architecture work - figure out per document listed on the front of docs.fedoraproject.org, where that specific piece of content best belongs. Is it user-facing, contributor-facing, both? Is it product / technology focused, or is it process / team oriented? Etc. Maybe draw up a big table. Then we can work on making sure those connections are set up in the new fedoraproject.org design.

Two more screenshots to show the global header in a product front page context and in a subpage context:

You put into words a lot of things that were in my mind. Thanks! Even the community part of the docs website now has a space on the main website, which I can see from the designs:) And you’re definitely correct about docs being more around “about fedora” and not the main website…it also contains a lot of to-dos and getting started information, which could be added in
to one of the buckets on the main website!

Yes, you could see an information architecture I tried to make for the website right now, but it covers a range of different articles!

Sure, I was actually conflicted whether I should pickthis up first, or pick up a landing page design flow for the docs website first! But it makes sense to first sort all data we have and then take better design decisions accordingly!

Thanks for this clarification, it was really helpful. I’d just want to know your view on this- @bcotton , since you have created an issue for the outreachy applicants regarding the docs website- what do you think about the direction this might head to?

2 Likes

That makes sense. I didn’t know the “front page” work was so far along. I agree with Mo’s general idea of how to think of the docs front page. I do think it will be a sort of catch-all destination, so it’s good to think about how it will present to users, too.

1 Like

I believe we have just a week for outreachy contributions-so I was thinking along those lines- but any ongoing work shouldn’t be constrained via such deadlines- so yep. I think for me I’d want to have a discussion with the design team and form an IA which would probably help everyone:)

I would think of it as something akin to the org overview on github where it just lists out the repos, like here’s the fedora design one:

Or even the pagure front page:
https://pagure.io

Associating the docs pages with the repos sounds intriguing. Could there be a one-to-one correlation between documentation pages and repos such that the former would provide a map of sorts to the latter? Maybe such a map would help to guide potential contributors to where we want them to go? It sort of seems logical that people would/should go to the documentation before going to the repo (to file an issue and/or submit a patch).