Refactor: reorganize, split into pages, and order by notability

[anishathalye]

This seems to be a very popular resource (the first result on Google when searching "dotfiles"). That's pretty awesome!

I think in its current state, the page has grown to a size where it is tough to navigate. See related issues #186 and #207.

In my opinion, some content could be removed, and the content overall could be organized better so that it is easier to navigate. I'm suggesting the following concrete changes:

1. Reorganize topics

I'd propose the following topic order and hierarchy. (The exact wording of the topic names can be tweaked.)

1. Tutorials
2. General-purpose dotfile utilities
3. Tool-specific frameworks
4. Bootstrap repositories
5. Dotfiles repositories for inspiration
6. Miscellaneous
7. FAQ

For some of the topics above, it's clear how the existing topics map over. I think this order better reflects the order in which new users should navigate the material.

In the hierarchy above, I've split the current "go further with a framework" into two top-level headings, separating the general-purpose utilities and following with the tool-specific stuff for shells/editors/etc.

I've also split "get started with a bootstrap" into two categories. Right now, the list contains various users' dotfiles (e.g. Abdullah's dotfiles are the first link on the entire page), most of which are not necessarily meant for others to build on top of. On the other hand, things like dotphiles look like they're actually meant as a bootstrap. I think the former can go into a "inspiration" section, whereas the bootstrap repositories can stay in a dedicated bootstrap section. The current bootstrap list also contains things like Awesome dotfiles, which is not a bootstrap repository; I propose things like this are moved to the Miscellaneous section. It also contains things like bashdot, which should be moved to the general-purpose dotfiles utilities section.

The miscellaneous section can contain everything that doesn't fit in any other category. This includes the current "tips and tricks" style content, like "don't ignore your .gitignore" and "embrace submodules / subtrees".

2. Split content across pages

I think the site is kind of intimidating and hard to navigate. I'd be in favor of splitting major topics across pages, and then adding some sort of navigation to go between the pages.

3. Write a brief intro for the homepage

With content split across pages, the homepage can have a brief text that introduces the user to the site and summarizes the idea of dotfiles management.

4. Remove some content

It might be nice to introduce some sort of notability criteria, e.g. as Homebrew does. I think their current criteria is (>= 20 forks OR >= 20 watchers OR >= 50 stars), but we could come up with our own.

This will help cut down on the overwhelming quantity of content on the site, and help navigate users to high quality projects rather than leaving it to chance which of the 1000 links they click on.

Stars/watchers/forks are a very rough proxy for the quality of a project, but I can't think of better alternatives.

5. Order existing content based on notability

Even with a notability criteria, I'd say it's worth ordering content based on a better metric than alphabetical order. Not to pick on this person in particular, but currently Abdullah's dotfiles (6 stars) are currently the first link on the page. Arguably, this is a less useful resource than e.g. Zach Holman's dotfiles (5.6k stars), which are currently buried deep in the "get started with a bootstrap section".

Sorting each of the topics based on stars helps solve this problem. Again, stars aren't the best metric, but I don't think there's a great alternative (and stars are better than alphabetical order!).

Another metric we could consider is number of users, but that might be hard to measure for certain frameworks. E.g. measuring it for Pathogen might be easy by analyzing public dotfiles repos on GitHub (because you can tell from vimrc contents), but measuring it for a program like stow might be hard, because you install the program on your machine to manage dotfiles, and it can't necessarily be deduced that someone's using stow from the contents of their dotfiles repo.

---

What are people's thoughts on this proposed reorganization? (cc @bedge @sparr, since they opened similar issues) And what do the maintainers think of this? (cc @unixorn)

If people are in favor of these changes, I'd be happy to do the implementation work.

[bedge]

I heartily endorse the above topical breakdown.

So long as I'm not doing the work, I'll toss out the notion of curated configs.
Blessed, managed, maintained, working, fully-functional as-is configurations with a semi-specific target audience,
eg:

• python dev with vim & zsh ala zplug
• java, intellij | vsc, zsh ala ohmyzsh
• perl/emacs/ksh (just kidding)
• etc

Or, is that what you, @anishathalye, mean by bootstrap repos?

The effort needed to pick each dot<thing> and read the readme's install, config, without stepping on the other, related, dot<thing> configs is ridiculous. Not to mention getting the path/completion/sort ordering right for the whole mess.

I'd pay a sub fee for an awesome everything env. I can't the the only vim/vsc/pycharm/zsh/zplug/aws with bits of java tossed in person.

[anishathalye]

Or, is that what you, @anishathalye, mean by bootstrap repos?

Yes, I think we are talking about similar things, though I don't know if we're talking about exactly the same thing.

Here's what I was thinking. Currrently, the website links to a ton of dotfiles repos in the "bootstrap" section. Most of them are just random people's dotfiles, and they aren't exactly designed to be used as-is by others, and in my opinion, they're more suitable as inspiration. But there are certain links like mathiasbynens' dotfiles in the current list that I think are more like "bootstrap" repos, in the sense that they are a good starting point for building on top of (or just using as-is with no modification).

Also, I'm not sure what exactly you meant by "curated configs" --- that seems like it could be tough. The current list does not make any attempt at curation; anyone could open a PR and add their stuff to it. I'm proposing some quantitative criteria for notability, and sorting by a quantitative criteria. Doing qualitative curation seems like it could be tough: who would decide what goes in the list?

[anishathalye]

This seems related to #2 / #3. @pengwynn, do you have any opinions on this issue?

[pengwynn]

Thanks @anishathalye. I'm onboard with the outlined work above. I also think we've outgrown our stock GitHub pages theme. I'm happy to contribute on the Jekyll side. Would love if we could round up some design help to create a clean layout that supports your proposed content hierarchy.

[anishathalye]

Cool! I could work on the content / refactoring over the holiday break. I'm comfortable enough with Jekyll that I could do the first attempt myself (it seems hard to parallelize), and I'll submit a WIP PR (and I'll definitely ask for help if I get stuck).

Where some collaboration / discussion might be helpful is things like deciding on notability criteria.

Moving away from the stock GH pages theme seems like a good change. Were you thinking of using some other open-source theme, perhaps modified to fit our needs, or having a fully custom design? Also, do you think the content / refactoring could be handled separately from the restyling? I agree that it would be awesome to have a new design, but I think the new content hierarchy is a fairly orthogonal change?

[unixorn]

I think refactor first, then we can pretty it up.

[neeasade]

One note: if we are sorting by stars or some other dynamic metric, then either you will need JS on the page to check the current star count via github API, OR you will need a script to generate the listing at deploy/static generation time (sometimes fully static page is an attractive quality, so something to consider)

[anishathalye]

I'd be in favor of avoiding JS.

We could have a script in the repo and periodically run it to re-sort the items, and then commit these changes. Someone would have to do this manually (or I could write a simple bot to do it).

Since the site is currently deployed with GitHub Pages, we can't really do it during generation time with something like a Jekyll plugin. Another option is that we could switch to doing deployments through Travis CI, and then we could do it automatically at deploy time. (I think it still wouldn't auto-update unless there are new commits, though.)

[unixorn]

I'd prefer to avoid JS-generated lists, if only because it'll add friction when people submit new collections.

[anishathalye]

I'm a little confused.

If we want sorting by stars (or whatever metric), some computation will need to happen. It could happen at commit time, deploy time, or page view time. Only the last option, page view time, requires JavaScript, the others can be more flexible in the exact method they use.

But based on my read on your comment, you'd prefer to avoid requiring a script that runs at commit time?

[unixorn]

I was unclear - I meant embedding javascript into the page. I like your idea of using travis/GH actions to render the markdown that is displayed from a source markdown file based on whatever metric we end up deciding on.