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

Also available in: Atom PDF