Documentation #503
closedFeedback on "new" documentation website <www.flashrom.org>
0%
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
Updated by Real One over 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.
Updated by Anastasia Klimchuk over 1 year ago
- Assignee set to Anastasia Klimchuk
Updated by Anastasia Klimchuk over 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!
Updated by Patrick Georgi over 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.
Updated by Patrick Georgi over 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.
Updated by Anastasia Klimchuk over 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
Updated by Anastasia Klimchuk about 2 months ago
- Status changed from In Progress to Resolved
Hello Real One, it has been a while, and we have migrated everything that we wanted to the new website. We are preparing to remove the old one.
If you are still here - you can tell what you think!
A few weeks ago, I went through your message once again, to check for ideas that we missed - and I found, I actually created two more patches.
But now I think that's it.
As a note, we had no goal to mirror the site structure 1:1 between old and new. So the structure has changed, but the goal is so that readers can find the info they are looking for.
As an overview,
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.
The home page now has direct link to Building from source, and there at the very beginning I added a reference to how to set up and clone git repo
Binary packages for various popular GNU/Linux distributions, BSD distributions and MS Windows; Dedicated windows wiki page.
I inspected what was on Downloads page about packaging, and added a link to repology.org to the home page (there you can see up-to-date link, package maintainers etc).
Packaging info on Downloads page was very outdated. There is no reason to copy this info, the source of truth is the distro page with maintainer info, latest version etc.
Windows doesn't have its own page, but it now has its own section in Building from source.
It has a TON of missing resources that return 404
That was one of the first things that we fixed (you can even see in the comments below).
As of right now, all the pages that have equivalent on the new website are redirected to new page.
There is no search feature
The search box in on the top left corner
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.
Yes, this is now on the home page
It has this gray-on-white with few color indications (terminal output), which is very boring and makes me sleepy.
The one thing that is still the same is the color theme. I might look into other themes once we remove old website, I wasn't thinking much about color theme :)
Updated by Real One about 1 month ago ยท Edited
Hi Anastasia,
First of all, I want to apologize for my temper when I first wrote this. I though that my issue would be disregarded like many other issues (from other projects), but that was not the case.
I also want to say that the current version of the new doc site is much better than it was at the moment I first wrote this issue, however I can still find some issues.
Now I know that this software's targeted to people who know what they are doing (programmers, hardware engineers, etc), but I don't think that anyone would prefer to look up the source code to find whether or not a chip/programmer/etc is supported or not, instead of looking at a nice organized and unified table sheet that has all the chips known to flashrom, color coded based on functionality (green for working, red for fail, yellow for dev, etc).
I see that you use Sphinx for docs, so maybe making such a table wouldn't be straightforward, but I think that having at least a unified list of all the chips (but still ordered and sectioned in categories) with some text next to it that tells the state of functionality would be great. Maybe even some NOTEs/WARNs/DEPRECATEDs if necessary.
Right now, https://www.flashrom.org/supported_hw/supported_flashchips.html leads you to the github page, to a C file that includes all the chips. So you have to manually go one dir up, search for the right file, and then search for the desired chip struct. Fortunately, there are not that many files, and they are named to easily find the company, but it's still a bummer to search thru all that, and if I'm not wrong, you can't even tell if the chip is fully supported.
A second issue would be accessibility and design. It's not a biggie and I know this is software that is not targeted to all people, but I think that all the text might be too cluttered in some areas, especially for the unordered lists. Some top-bottom margins/paddings may make it a bit better.
I also think that the "Building / installing / packaging" section deserves it's own page, maybe even with a call-to-action button/link.
I still stay strong on offering instructions on how to install flashrom using the commonly-known package managers (apt, pacman, portage, winget, brew, etc), as well as links to distro packages (packages.gentoo.org, archlinux.org/packages, etc).
And I personally think that the emergency help should appear somewhere at the top of the main page, so you don't have to scroll down in order to see that message (I have a laptop with less than 1920x1080, and yes you can even find new ones for some reason, and so the emergency help container is out of the viewport when entering the page), because you might not even scroll down when you're in panic-mode. Actually why not adding this warning to more pages a user might access when searching for this kind of help?
I any case, I want to thank you for the changes you've made so far. It's really great to see that!
Updated by Anastasia Klimchuk about 1 month ago
Hello, thank you so much for your nice message! I appreciate your detailed ideas. I always try to imagine "what would a new person who is just reading the docs for the first time think?" , but I know I am not that new person anymore, so I value the ideas other people share.
Firstly, the bookkeeping: I closed this ticket because it was more of a broad overview, and also because we now officially moved to a new website as the only one. For the future, we better be creating separate tickets, more granular, for concrete ideas. Or, if something can be done straight away, it can be a patch straight away.
You have an account here already, you are welcome to create new tickets with specific ideas - you can even assign them to me straight away!
For details, few things from your message:
Now I know that this software's targeted to people who know what they are doing (programmers, hardware engineers, etc), but I don't think that anyone would prefer to look up the source code to find whether or not a chip/programmer/etc is supported or not, instead of looking at a nice organized and unified table sheet that has all the chips known to flashrom, color coded based on functionality (green for working, red for fail, yellow for dev, etc).
We have a plan to do this, and the ticket is this: https://ticket.coreboot.org/issues/543
You can add yourself as a Watcher for that ticket, also you can add comments on the ticket.
Tables would be perfect, no doubt about that. The situation about tables on the old wiki was that they needed to be updated manually, and time showed that no one was doing it. Concretely, they were last updated in 2013 or so. I joined at the very end of 2020 and it was like this.
So the main challenge is to make it auto-updated, because humans forget, and humans are busy, also humans come and go.
Right now, https://www.flashrom.org/supported_hw/supported_flashchips.html leads you to the github page, to a C file that includes all the chips. So you have to manually go one dir up, search for the right file, and then search for the desired chip struct. Fortunately, there are not that many files, and they are named to easily find the company, but it's still a bummer to search thru all that, and if I'm not wrong, you can't even tell if the chip is fully supported.
This is a good observation, and I made a patch for it https://review.coreboot.org/c/flashrom/+/86953
If you have an account in our Gerrit (or you can create one), you can review the patch. If not, it's fine, no prob, I will ask someone else to review.
I also think that the "Building / installing / packaging" section deserves it's own page, maybe even with a call-to-action button/link.
This page exists: https://flashrom.org/dev_guide/building_from_source.html
and it is linked from the home page.
However, in your point of view, is it discoverable?
I did add a few links to the home page recently, so just to check whether you were looking at the latest version?
These two items:
I still stay strong on offering instructions on how to install flashrom using the commonly-known package managers
And I personally think that the emergency help should appear somewhere at the top of the main page
Good ideas to think about - and I mean thinking on a background of how to make these sections in the docs better.
Is it possible that you can create two tickets for these? You can assign to me.
I will be thinking about it, if I get an idea I will update the tickets. I can't promise the exact dates when "everything will be done", but it's good to have it on the list of open tickets , so not to forget