Project

General

Profile

Actions

Documentation #503

open

Feedback on "new" documentation website <www.flashrom.org>

Added by Real One about 1 year ago. Updated about 1 year ago.

Status:
In Progress
Priority:
Normal
Category:
-
Target version:
Start date:
08/07/2023
Due date:
% Done:

0%

Estimated time:

Description

This github issue is my personal feedback on flashrom's "new" documentation website.

TL;DR: The new website is horrible & lacks a lot of information and the "old" wiki is way more better.
No download instructions

The new website doesn't have any download instructions, just building instructions. As a beginner, you can't tell where you should download the code. It just tells you how to build from the source where you are supposed to figure out how and where to download from.

On the other hand, the "old" wiki has a dedicated downloads page that is directly visible from the start page which tells you pretty much everything:

  • Required dependencies;
  • How to get the source code with git;
  • Binary packages for various popular GNU/Linux distributions, BSD distributions and MS Windows; Dedicated windows wiki page.

It has a TON of missing resources that return 404

Trying to find a way to write a feedback to this project regarding this, I've noticed many webpages were missing, with the server returning me 404.
Even harder to find what you need

There is no search feature, pages you'd expect to find your answer don't really work, etc.

For instance, I was trying to find the list of supported programmers. In return, the website hit me with this mess:

image

Like seriously, what is this mess?! Inserting man pages is not really helpful.

The old wiki on the other hand, has a dedicated page listing with images the supported programmers, which makes the difference.
Ugly

I like the idea of minimalism, which is what a lot of websites should adopt, however this is way too simple and confusing.

The old wiki had more features like tables with images and colors indicating certain stuff, and I also really like the "Emergency help" red box (see below), which just gives the end user the idea that what they are doing could be potentially fatal and other important instructions.

image

The new website does not have these important features, which makes it hard to follow. It has this gray-on-white with few color indications (terminal output), which is very boring and makes me sleepy. Documentation shouldn't be boring, but be rather important.
"Anon, you can't just leave your feedback here, this is the official flashrom github repository, not a place where you can leave your feedback"

I think that's true, but in the same time it was hard for me to really pick something from the Contact page.

First, there is no feedback section where I can really send this.

Second of all, I wanted to voice my oppinion to more people.

I could have easily just sent this to flashrom@flashrom.org, but here are my answer scenarios:

"We are sorry, but this is not the support channel, so if you want to send your feedback, send it to something@flashrom.org";
"Thank you for sending us your feedback. Your feedback is very important for us, and we'll keep that in mind" and then *the only person who read my feedback would forget about it, the feedback would be forever forgotten;
No answer and nothing would be achieved.

An apology message for being too harsh on the situation and thanking in advance

I don't really mean to be too harsh about the situation, but I've had really good anticipations about flashrom, praising it for a few months. Seeing how big of a downgrade got the documentation page made me really frustrated, which made me voice my criticism on the documentation website.

The program itself is quite good, can't complain about it. However, there were occasions where I had to troubleshoot the situation, and I would visit wiki.flashrom.org out of instinct. Today I visited it's domain - flashrom.org - just to see if something else is on this domain. I was very surpised to see how bad the documentation on that website was, and just assumed it was the old documentation, but the "Old wiki website" revealed that it is the otherwise.

In conclusion, I want to apologize on being too critic, I hope some people will really read this, I hope the developers will work on the documentation website, I want to apologize for any grammar & typo errors and I want to thank you in advance.

TheRealOne78

Actions #1

Updated by Real One about 1 year ago

  • Tracker changed from Bug to Documentation
Actions #2

Updated by Real One about 1 year ago

Turns out I can't really edit the body of the message, so please see https://github.com/flashrom/flashrom/issues/307 for markup inconsistencies, as transitioning from GitHub to this bugtracking website is a little problematic.

Actions #3

Updated by Anastasia Klimchuk about 1 year ago

  • Assignee set to Anastasia Klimchuk
Actions #4

Updated by Anastasia Klimchuk about 1 year ago

  • Status changed from New to In Progress

TheRealOne78 (sorry I don't know your name), thank you so much for creating this ticket!
I really, seriously, appreciate this, that you spent your time, and wrote all of your thoughts!
All of this feedback is very useful, and won't be lost. It will take some time to fix everything, but it will happen eventually.

The plan was, and is, to roll out new website very early with just few pages and lock wiki for editing. And the, wiki stays available in view-mode for as long as needed, for the time needed to migrate the pages to new site.

So what you see that there is not much info in new website: this is expected, but it is just a starting point. This is why wiki is linked in the menu of new site, for easy access.
Also the information from wiki won't be thrown away, absolutely not. It needs some time to get migrated, and also lots of pages are old (like 10yr old or more) and they can benefit from reviewing from active members of community.

If you are wondering why we didn't migrate all the pages first and then switch to the new website. Because, it woudn't work: it would take too long a time and during this long time having two sources of info would be a disaster. Those two sources of info would diverge and at the end no one knows where the truth is. Right now, all updates go to new website and wiki is locked for editing. Very soon I will add a banner to wiki which explains that it is retired and not updated anymore.

What do you do now:
If you are looking for information, and there is no such page on new site, look on wiki. It is normal to look for info on wiki while it's not migrated yet.
If you notice more issues to report: please report, that is useful! You can create new tickets, or add comments to this one. Either way, you are very welcome.
Finally, if you would like to contribute to documentation, you are welcome to send a patch. This is optional, only if you want to.

Thank you so much!

Actions #5

Updated by Patrick Georgi about 1 year ago

Point taken on the 404s. I have "set up redirects" on my agenda, just didn't get to it yet. I'll report here when that's done (Anastasia sent me a list of patterns already), and afterwards I'll gladly resolve all missing URLs with a redirect.

Actions #6

Updated by Patrick Georgi about 1 year ago

So I finally got to set up the redirect mechanism that falls back to sending people over to wiki.flashrom.org if a URL isn't found and there's no manual redirect configured (also new). That way, https://www.flashrom.org/Contact points to https://www.flashrom.org/contact.html with a permanent redirect (which tells search engines and the like that the old URL is deprecated), while https://www.flashrom.org/Supported_programmers currently points to https://wiki.flashrom.org/Supported_programmers with a temporary redirect (so it can be retargeted to a new-and-official location for that doc once we determined what that would be).

I'm also working on extending the wiki so its own pages redirect to the new canonical locations (wo wiki.flashrom.org/Contact redirects to www.flashrom.org/contact.html).

It's a bit convoluted to set up the permanent redirects. I'll discuss with Anastasia how to share the work, but for now, send any proposals for such mappings (old URL -> new URL) my way and I can put them in.

Actions #7

Updated by Anastasia Klimchuk about 1 year ago

Update on a few other things mentioned in the initial post.

An emergency help red box was missing, I added it, on the home page.

About colours and theme. I don't mind a splash of colour, and entirely possible it will be added later. To begin with, we started using one of built-in sphinx themes because it's the easiest to wire in. Also this theme, out of other built-in ones, is adaptive to various screen sizes which is a good practical point.

About sending feedback, it would be no problem at all to send it to mailing the list. Most likely, the same people would respond. And I would likely create a ticket anyway. Because I think bugtracker is the right place for bugs, so you did the right thing. For future, if you want to send a feedback for anything, either way is fine: any of the options listed on the contact page is fine.

One more thing, you mentioned
As a beginner, you can't tell where you should download the code
There is a section in dev guides which I think answers this question:
https://www.flashrom.org/dev_guide/development_guide.html#set-up-the-git-repository-and-dev-environment

Actions

Also available in: Atom PDF