starred/ArchiveBox

Fork 0

mirror of https://github.com/ArchiveBox/ArchiveBox.git synced 2026-04-25 17:16:00 +03:00

[GH-ISSUE #1350] Question: First time user confusion/documentation feedback #2337

New issue

Closed

opened 2026-03-01 17:58:17 +03:00 by kerem · 3 comments

kerem commented

2026-03-01 17:58:17 +03:00

Owner

Originally created by @Feuermurmel on GitHub (Feb 18, 2024).
Original GitHub issue: https://github.com/ArchiveBox/ArchiveBox/issues/1350

Hey!

I'm not invested in this tool yet, and I don't have a lot of time to report the few things I noticed (e.g I didn't thoroughly search for already-open issues). I'd be glad if a maintainer takes 10 minutes of their time to go over these points and maybe ping the right people and/or create/update issues. I don't expect more and I'm also happy if this issue is just going to be closed.

I definitely think this tool does an important job, an seeing what it can be used for, I'm happy that it exist.

I'm a first-time user and the issues here are all probably tied to me being unaware of most of everything. These are just pointers/ideas about things could have improved my experience as a first-time user:

The main web page is really hard to follow for me. There is no clear structure (e.g. a TOC or headings that stand out). The many and colorful icons, emoji, decorative graphics, LEGOs all scream "look at me" without telling me what's important to look at first.

I'm on the neurodivergent spectrum, that might amplify this impression.
The subcommand descriptions in archivebox --help are not wrapped correctly, making them hard to read:
I went the route of manually installing dependencies, as descibed under Install (Bare Metal Setup). I know I'm asking for trouble. I installed all the stuff with brew and pip, skipping playwright install ... because I have Google Chrome on my machine.

I run archivebox add and get this error:
```
[+] [2024-02-18 17:27:37] "example.com"
    https://example.com
    > ./archive/1708277257.810526
      > favicon
      > headers
      > wget
      > title
      > readability
        Extractor failed:
            FileNotFoundError [Errno 2] No such file or directory: 'readability-extractor'
```
I can probably fix this, but I think the need to install readability-extractor should be mentioned somewhere on Install.

I later found out that archivebox --version tells me what's missing in great detail. This is cool. If the installation page simply said that I should run archivebox --version and make the warnings go away, that would already be an improvement because then I wouldn't be suprised to see a warning/error when running archivebox add.
While browsing, I found the documentation at https://docs.archivebox.io/en/latest/index.html. This The example shows using archivebox info, but I think that subcommand doesn't exist.
It seems documentation for verstions newer than v0.6.2 are missing on https://docs.archivebox.io.
I'm trying to get an overview of what all the subcommand do, I'm looking for something like a man page with all the info on one page. This is my preferred way to get to know a new tool. I don't think that exists? I've looked at:

Thanks!

Originally created by @Feuermurmel on GitHub (Feb 18, 2024). Original GitHub issue: https://github.com/ArchiveBox/ArchiveBox/issues/1350 Hey! I'm not invested in this tool yet, and I don't have a lot of time to report the few things I noticed (e.g I didn't thoroughly search for already-open issues). I'd be glad if a maintainer takes 10 minutes of their time to go over these points and _maybe_ ping the right people and/or create/update issues. I don't expect more and I'm also happy if this issue is just going to be closed. I definitely think this tool does an important job, an seeing what it can be used for, I'm happy that it exist. I'm a first-time user and the issues here are all probably tied to me being unaware of most of everything. These are just pointers/ideas about things could have improved my experience as a first-time user: - The [main web page](https://archivebox.io/) is really hard to follow for me. There is no clear structure (e.g. a TOC or headings that stand out). The many and colorful icons, emoji, decorative graphics, LEGOs all scream "look at me" without telling me what's important to look at first. I'm on the neurodivergent spectrum, that might amplify this impression. - The subcommand descriptions in `archivebox --help` are not wrapped correctly, making them hard to read: <img width="570" alt="image" src="https://github.com/ArchiveBox/ArchiveBox/assets/50332/eca544f0-ffe7-4a85-95df-8dc360ca9b17"> - I went the route of manually installing dependencies, as descibed under [Install (Bare Metal Setup)](https://github.com/ArchiveBox/ArchiveBox/wiki/Install#option-c-bare-metal-setup). I know I'm asking for trouble. I installed all the stuff with `brew` and `pip`, skipping `playwright install ...` because I have Google Chrome on my machine. I run `archivebox add` and get this error: ``` [+] [2024-02-18 17:27:37] "example.com" https://example.com > ./archive/1708277257.810526 > favicon > headers > wget > title > readability Extractor failed: FileNotFoundError [Errno 2] No such file or directory: 'readability-extractor' ``` I can probably fix this, but I think the need to install `readability-extractor` should be mentioned somewhere on [Install](https://github.com/ArchiveBox/ArchiveBox/wiki/Install). *I later found out that `archivebox --version` tells me what's missing in great detail. This is cool. If the installation page simply said that I should run `archivebox --version` and make the warnings go away, that would already be an improvement because then I wouldn't be suprised to see a warning/error when running `archivebox add`.* - While browsing, I found the documentation at https://docs.archivebox.io/en/latest/index.html. This The example shows using `archivebox info`, but I think that subcommand doesn't exist. - It seems documentation for verstions newer than v0.6.2 are missing on https://docs.archivebox.io. - I'm trying to get an overview of what all the subcommand do, I'm looking for something like a man page with all the info on one page. This is my preferred way to get to know a new tool. I don't think that exists? I've looked at: - https://archivebox.io/#usage - https://github.com/ArchiveBox/ArchiveBox/wiki/Usage#cli-usage - Searched on https://docs.archivebox.io//en/v0.6.2/index.html Thanks!

kerem closed this issue

2026-03-01 17:58:17 +03:00

kerem commented

2026-03-01 17:58:18 +03:00

Author

Owner

@pirate commented on GitHub (Feb 19, 2024):

The [main web page](archivebox.io) is really hard to follow for me.

The only relevant section to get started is the Quickstart section, but the Github README really serves as the main landing page. ArchiveBox.io is auto-generated by Github Pages with a default Jekyll theme they provide, I historically haven't spend time customizing the default CSS as I focus on making sure the README markdown looks good in Github as thats where the majority of our traffic comes in.

(e.g. a TOC or headings that stand out)

There is a README TOC built in to Github, just click the little menu icon in the upper right.

The subcommand descriptions in archivebox --help are not wrapped correctly

help outputs (and most CLIs in general outside of pagers like less) are generally not wrapped by most tools (e.g. docker help). Also 80 chars is too narrow anyway to reasonably wrap to, just drag your window bigger!

I run archivebox add and get this error: FileNotFoundError [Errno 2] No such file or directory: 'readability-extractor'

All of our install instructions (wiki and README) include archivebox setup or archivebox init --setup which installs this for you automatically. Did you run that?

I later found out that archivebox --version tells me what's missing in great detail.

All of the install instructions also tell you to run archivebox version at some point, where did you find instructions without that? If you can provide a link or screenshot of where that is missing that would be helpful.

While browsing, I found the documentation at docs.archivebox.io/en/latest/index.html. This The example shows using archivebox info, but I think that subcommand doesn't exist.

info is an older command that doesn't exist in newer versions, that will be fixed once those docs are updated to 0.7.2.

It seems documentation for versions newer than v0.6.2 are missing on docs.archivebox.io.

Yes, the build for the stable branch was broken, should be fixed this week, but in the meantime the latest docs are available here: https://docs.archivebox.io/en/dev/. Note our Wiki is always the most up-to-date docs source and (the ReadTheDocs site is just a clone of the wiki with a nicer UI and contains all the same content).

I'm looking for something like a man page with all the info on one page

Just run archivebox help, it shows all the subcommands and what they do.

archivebox help

archivebox [subcommand] --help   # you can also append --help or -h to any subcommand for more info

There are also function raw signatures available here if you want more: https://docs.archivebox.io/en/dev/archivebox.html#module-archivebox.main

@pirate commented on GitHub (Feb 19, 2024): > The [[main web page](https://archivebox.io/)]([archivebox.io](https://archivebox.io/)) is really hard to follow for me. The only relevant section to get started is the **Quickstart** section, but the Github README really serves as the main landing page. ArchiveBox.io is auto-generated by Github Pages with a default Jekyll theme they provide, I historically haven't spend time customizing the default CSS as I focus on making sure the README markdown looks good in Github as thats where the majority of our traffic comes in. > (e.g. a TOC or headings that stand out) There is a README TOC built in to Github, just click the little menu icon in the upper right. <img width="500" alt="image" src="https://github.com/ArchiveBox/ArchiveBox/assets/511499/bbf4d826-bc1b-4f58-81f1-2d5e7d9e9901"> --- > The subcommand descriptions in archivebox --help are not wrapped correctly `help` outputs (and most CLIs in general outside of pagers like `less`) are generally not wrapped by most tools (e.g. `docker help`). Also 80 chars is too narrow anyway to reasonably wrap to, just drag your window bigger! --- > I run archivebox add and get this error: `FileNotFoundError [Errno 2] No such file or directory: 'readability-extractor'` All of our install instructions (wiki and README) include `archivebox setup` or `archivebox init --setup` which installs this for you automatically. Did you run that? --- > I later found out that archivebox --version tells me what's missing in great detail. All of the install instructions also tell you to run `archivebox version` at some point, where did you find instructions without that? If you can provide a link or screenshot of where that is missing that would be helpful. --- > While browsing, I found the documentation at [docs.archivebox.io/en/latest/index.html](https://docs.archivebox.io/en/latest/index.html). This The example shows using archivebox info, but I think that subcommand doesn't exist. `info` is an older command that doesn't exist in newer versions, that will be fixed once those docs are updated to 0.7.2. --- > It seems documentation for versions newer than v0.6.2 are missing on [docs.archivebox.io](https://docs.archivebox.io/). Yes, the build for the stable branch was broken, should be fixed this week, but in the meantime the latest docs are available here: https://docs.archivebox.io/en/dev/. Note our Wiki is always the most up-to-date docs source and (the ReadTheDocs site is just a clone of the wiki with a nicer UI and contains all the same content). --- > I'm looking for something like a man page with all the info on one page Just run `archivebox help`, it shows all the subcommands and what they do. ```bash archivebox help archivebox [subcommand] --help # you can also append --help or -h to any subcommand for more info ``` There are also function raw signatures available here if you want more: https://docs.archivebox.io/en/dev/archivebox.html#module-archivebox.main

kerem commented

2026-03-01 17:58:18 +03:00

Author

Owner

@Feuermurmel commented on GitHub (Feb 28, 2024):

Thank's for the thorough response!

I'll try to give some more details:

The main web page is really hard to follow for me.

The only relevant section to get started is the Quickstart section, but the Github README really serves as the main landing page. ArchiveBox.io is auto-generated by Github Pages with a default Jekyll theme they provide, I historically haven't spend time customizing the default CSS as I focus on making sure the README markdown looks good in Github as thats where the majority of our traffic comes in.

I don't think that custom styling would improve the situation. It's more about how the content is structured and how styling/icons are used to structure it. The README.md on GitHub is just as hard for me to follow.

The subcommand descriptions in archivebox --help are not wrapped correctly

help outputs (and most CLIs in general outside of pagers like less) are generally not wrapped by most tools (e.g. docker help).

I'm used to tools in the Python ecosystem doing that (e.g. pip --help). Why argparse does wrap the help test for arguments but not for subcommands is beyond me. So ArchiveBox is just seeing the default behavior of argparse and I understand that you wouldn't invest a lot of time find a workaround for that.

Also 80 chars is too narrow anyway to reasonably wrap to, just drag your window bigger!

Please spare your condescending comments, they don't improve anyone's situation. I know that I can make my terminal wider. I hope you're assuming that I have my terminal at 80 columns for a reason and not just because I never thought about changing Terminal.app's settings.

I run archivebox add and get this error: FileNotFoundError [Errno 2] No such file or directory: 'readability-extractor'

All of our install instructions (wiki and README) include archivebox setup or archivebox init --setup which installs this for you automatically. Did you run that?

I think I followed the instructions under 2. Install ArchiveBox using pip.

I did not look at 3. Prepare your URLs for importing or the following sections. These did not seem to be part of the installation instructions anymore ("Prepare your URLs for importing") and I probably moved to looking for more thorough usage documentation, probably ending up at Usage.

I think I never came across instructions telling me to run archivebox setup or archivebox init --setup as part of the installation process.

I later found out that archivebox --version tells me what's missing in great detail.

All of the install instructions also tell you to run archivebox version at some point, where did you find instructions without that? If you can provide a link or screenshot of where that is missing that would be helpful.

I think this stems from the same issue that the installation instructions under Option C. Bare Metal Setup are very confusing for me. Installation of the software, creating an archive and preparing imports are all mixed up in a single guide. If I followed all those instructions from start to finish, I might not have run into this problem, but I assume that is not the intention? Aren't sections 1 and 2 meant as alternatives to install ArchiveBox?

I think this confusion could be helper by changing the levels of the different headings and adding archivebox setup and archivebox version to a separate section called e.g. "Installing additional dependencies".

I'm looking for something like a man page with all the info on one page

Just run archivebox help, it shows all the subcommands and what they do.
archivebox help

archivebox [subcommand] --help   # you can also append --help or -h to any subcommand for more info

I see that now. I think what threw me off is that archivebox help/-h behaves differently whether I'm in an initialized archive or not, which I find a strange choice. I may have run that command in a new shell at ~, which is common for me to do, and just assumed that there is no further on-line documentation. That made me look for a man page or similar, which I didn't find.

There are also function raw signatures available here if you want more: https://docs.archivebox.io/en/dev/archivebox.html#module-archivebox.main

Cool, thanks for the pointer!

@Feuermurmel commented on GitHub (Feb 28, 2024): Thank's for the thorough response! I'll try to give some more details: > > The [main web page](https://archivebox.io/) is really hard to follow for me. > > The only relevant section to get started is the **Quickstart** section, but the Github README really serves as the main landing page. ArchiveBox.io is auto-generated by Github Pages with a default Jekyll theme they provide, I historically haven't spend time customizing the default CSS as I focus on making sure the README markdown looks good in Github as thats where the majority of our traffic comes in. I don't think that custom styling would improve the situation. It's more about how the content is structured and how styling/icons are used to structure it. The `README.md` on GitHub is just as hard for me to follow. > > The subcommand descriptions in archivebox --help are not wrapped correctly > > `help` outputs (and most CLIs in general outside of pagers like `less`) are generally not wrapped by most tools (e.g. `docker help`). I'm used to tools in the Python ecosystem doing that (e.g. `pip --help`). Why `argparse` does wrap the help test for arguments but not for subcommands is beyond me. So ArchiveBox is just seeing the default behavior of `argparse` and I understand that you wouldn't invest a lot of time find a workaround for that. > Also 80 chars is too narrow anyway to reasonably wrap to, just drag your window bigger! Please spare your condescending comments, they don't improve anyone's situation. I know that I can make my terminal wider. I hope you're assuming that I have my terminal at 80 columns for a reason and not just because I never thought about changing Terminal.app's settings. > > I run archivebox add and get this error: `FileNotFoundError [Errno 2] No such file or directory: 'readability-extractor'` > > All of our install instructions (wiki and README) include `archivebox setup` or `archivebox init --setup` which installs this for you automatically. Did you run that? I think I followed the instructions under [2. Install ArchiveBox using `pip`](https://github.com/ArchiveBox/ArchiveBox/wiki/Install#2-install-archivebox-using-pip). I did not look at [3. Prepare your URLs for importing](https://github.com/ArchiveBox/ArchiveBox/wiki/Install#3-prepare-your-urls-for-importing) or the following sections. These did not seem to be part of the installation instructions anymore ("Prepare your URLs for importing") and I probably moved to looking for more thorough usage documentation, probably ending up at [Usage](https://github.com/ArchiveBox/ArchiveBox/wiki/Usage). I think I never came across instructions telling me to run `archivebox setup` or `archivebox init --setup` as part of the installation process. > > I later found out that archivebox --version tells me what's missing in great detail. > > All of the install instructions also tell you to run `archivebox version` at some point, where did you find instructions without that? If you can provide a link or screenshot of where that is missing that would be helpful. I think this stems from the same issue that the installation instructions under [Option C. Bare Metal Setup](https://github.com/ArchiveBox/ArchiveBox/wiki/Install#option-c-bare-metal-setup) are very confusing for me. Installation of the software, creating an archive and preparing imports are all mixed up in a single guide. If I followed all those instructions from start to finish, I might not have run into this problem, but I assume that is not the intention? Aren't sections 1 and 2 meant as alternatives to install ArchiveBox? I think this confusion could be helper by changing the levels of the different headings and adding `archivebox setup` and `archivebox version` to a separate section called e.g. "Installing additional dependencies". > > I'm looking for something like a man page with all the info on one page > > Just run `archivebox help`, it shows all the subcommands and what they do. > > ```shell > archivebox help > > archivebox [subcommand] --help # you can also append --help or -h to any subcommand for more info > ``` > I see that now. I think what threw me off is that `archivebox help/-h` behaves differently whether I'm in an initialized archive or not, which I find a strange choice. I may have run that command in a new shell at `~`, which is common for me to do, and just assumed that there is no further on-line documentation. That made me look for a man page or similar, which I didn't find. > There are also function raw signatures available here if you want more: https://docs.archivebox.io/en/dev/archivebox.html#module-archivebox.main Cool, thanks for the pointer!

kerem commented

2026-03-01 17:58:18 +03:00

Author

Owner

@pirate commented on GitHub (Feb 29, 2024):

I clarified that Step 1 and 2 are not alternatives, they're in sequence and the whole sequence needs to be followed. I also moved adding URLs to Next Steps: at the bottom.

https://github.com/ArchiveBox/ArchiveBox/wiki/Install#2-install-the-python-dependencies-using-pip

@pirate commented on GitHub (Feb 29, 2024): I clarified that Step 1 and 2 are not alternatives, they're in sequence and the whole sequence needs to be followed. I also moved `adding URLs` to `Next Steps:` at the bottom. https://github.com/ArchiveBox/ArchiveBox/wiki/Install#2-install-the-python-dependencies-using-pip

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/ArchiveBox#2337

No description provided.

Rows
Columns