Architecture and UI discussion

[mirisuzanne]

This is a great start! Here's a place for discussing UI architecture and goals from the start, so technical concerns don't end up driving the interface. This is not about the paint job (I know that will come) - but about what information is most useful, who it's useful to, how we get it, and how users find it.

I see two main users of the site:

1. Extension Authors want to make their extensions available, and have them easily accessed by extension users. The more this can automate off information already stored in a repo, the easier it will be.
2. Extension Users are looking for tools to help them build websites — either by extension name (they heard it somewhere), or by categories/tags (buttons, grids, frameworks...), or possibly by author? Some might even browse to see what's available.

[mirisuzanne]

Here's a few things that struck me on first loading the site. Not as complaints about the rough sketch that's there, but to generate ideas about where we're headed. Excited to see it coming together!

• As soon as there are more than a few extensions, tagging and other sort features will become really important for finding extensions you don't know by name. Browsing isn't viable unless we have good tools for filtering/sorting/featuring or voting to help make the list more manageable.
• When I'm logged out it's not clear to me what steps are needed to add my extension.
• The initial form is daunting. What fields here are absolutely required? For example: I was worried by "version" and "sass version" because I may not remember to come back and update some site every time I make updates to any of my extensions. That's the sort of info I like to manage inside the repo, and not worry about anywhere else. The various download URLs are also auto-generated for me by github and rubygems — so not something I think of as my details to manage, if that makes sense.
• Tags are easy to add. Long description is harder. Extra install details are a real pain. I wonder if there's a simple form and then more advanced options?
• It wasn't clear to me if/when/how I'd be able to edit, until after I saved.

[jlong]

Hey Eric!

I like your ideas about revamping the on boarding process. Would you be willing to pull together some wireframes or mockups outlining how you think it should work? Any revamp of that should include support for a sassmanifest.json file in the root of a repo that can specify the attributes/README/INSTALL stuff. Once we have support for that, a lot of the extra fields will go away for most users.

To be clear I'd like folks to be able to add a basic extension without creating a sassmanifest.json file. A Sass extension should be as simple as a folder of Sass files somewhere on the Internet -- no manifest required.

Any chance you could get us some drawings on this stuff at some point this weekend?

--John

[jamiebuilds]

On Architecture:
I see a lot of ways this could mimic bower as a package manager, using files like sass.json and .sassrc, that allow you to publish once and it always stay up to date by pulling from tags/commits in the public git repo. Even taking it one step further and adding dependancies to sass's load paths.

It'd be nice for packages to revolve around repositories (Git, SVN) and not files floating around the web. For once thing, I'd never use a package that wasn't versioned and licensed, with a readme and a public place to report issues and communicate with the author, and I'm not the only one. As far as I can see, most open source sass projects are already up on Github.

I would absolutely require a manifest file, they are ridiculously simple (npm init, bundle init, bower init), if someone wanted their package to be used by others, writing a 6 line long json file shouldn't be too difficult. Just having a name, version, description, main, enables easy management of packages.

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My project does this amazing thing",
  "main": "path/to/main.scss"
}

Above: not a big deal

On UI:
The most simple search tool can go a long way. Features like filtering and tagging can and should be later concerns. Look how far tools like bower and component have gone without anything more than a search field.

In terms of information, as a package consumer I'd want to see the title, description, repo url, and license.

[jhardy]

At SassConf @hatefulcrawdad and I built a working prototype using a bower approach. You can test it out here,
http://young-meadow-1396.herokuapp.com/ you can see an example sassmanifest.json file here https://github.com/jhardy/compass-ceaser-easing/blob/master/sassmanifest.json

This prototype works and if you want to add a sassmanifst.json file to a repo and then paste the github repo ssh url in to the protoype site, it should be added to the page.

We also build out some basic user profiles leveraging github, you can see mine here http://young-meadow-1396.herokuapp.com/users/jhardy

We need to add a basic search and filtering system the this prototype which would not be hard.

We like this approach because it simplifies the project, requires no additional registrations and heavily relies on github where most of the packages would live. We would still need to develop a way to have the site update the items on the registry in our prototype but that could be done with a cron job or maybe we can think up some other ideas.

I would love some feedback on the prototype site and I personally feel the bower approach is the correct way to go, but I am not opposed to @jlong approach with a more full featured backend and auth system, but I feel it may be a little overboard for the needs of the project after thinking about it more the past day.

Edit:
Forgot to mention the backend we built is here https://github.com/jhardy/sassy-toolbox-rails

Edit 2:
styles @hatefulcrawdad did are here: https://github.com/hatefulcrawdad/sassy-toolbox and are not final of course was just a fun hack project during the conference and we believe we should probably take this design and movie it closer to the sass-lang.com site.

[hatefulcrawdad]

The approach above also would use a really unobtrusive approach to tags, just clicking the tag to filter the page by one filter at a time. We could easily layer in search as well. Our goal, like Jared mentioned, was to create a really simple way to list extensions using a pretty familiar method that requires zero command line experience at all. We are open to either approach but feel like simpler is better to get going.

[jlong]

Hey guys,

I thought we had agreed to try and merge both approaches?

@jhardy As I said before I like the bower approach, but I want to build something that designers and programmers can use to share extensions. Particularly for designers, technology can be a big barrier for them to be involved at all. Requiring Git sounds like a bad idea to me.

Also, while I love GitHub, not everyone wants to host their project there. We should be careful about building something that is centered on one company's version of a technology. It can be the easy path, but I don't think it should be the only path.

I can work on pulling over the code from your repo for the manifest stuff if you guys are having trouble figuring out how it will work. I'm very grateful for the code and the thinking that has gone into it. I don't think it will be that hard to make the two approaches work together. And well have a stronger system for it.

--John

[mirisuzanne]

Great thoughts! I see both sides of this, but I think they cover fairly different use-cases, and we should maybe treat them differently in more ways than just point-of-access.

1. If something is intentionally built and maintained as a plugin with versioning, etc, I think it's safe to insist on version control and a manifest. I think a well-documented manifest approach handles this use-case quite well. For people maintaining plugins over the long term, keeping all the data inside the repo, and automating parts off github is a huge win. For this sort of advanced integration, I think it's ok to start with some common technical restrictions (e.g. GitHub) even if we want to broaden our scope in the long-term. We have to start somewhere.
2. Supplying a way for truly non-technical designers to share smaller extensions is really cool, but I would make it a much simpler thing all-around — without any concept of versioning, automated installation, etc. This could be pared down to the bare minimum helpful for browsing links to code: name, authors, description, and URL? It's probably a good idea to include licenses here too, but I wouldn't require it, and I'd provide common licenses to choose from (see githubs new-repo form). I doubt many of these will come with a license pre-attached.

I would personally submit projects at both levels. I have some plugins that I maintain as such, and others that are really just useful scraps of code. As a contributor, I would rather see each type of extension treated as it's own use-case, rather than have them shoe-horned into a single compromise API.

I can try to rough-up some sketches tomorrow, we'll see. Happy to see other people's ideas as well!

[jhardy]

@jlong, I still really like the idea of combing both approaches, I was just soliciting feedback for what we had built based using the bower syntax, I should have been more explicit. I plan on merging our work into your repo this week and seeing what we can do to bring them both inline and function correctly.

I agree with Eric in that if we are going to support a way for non-technical users to supply extensions, the form will need to be much simpler.

[mirisuzanne]

I'm going back-and-forth on the form approach. We need to think real hard about what it is that non-technical users would want to do, how they would use this, why, and how we can help? Before I can really draw up a proposal, I'd like to see some much clearer use-cases.

Since we're talking about sharing code, I wonder if our goal with non-technical users should actually be helping teach them the important tech. Maybe instead of helping them bypass version control, we should be finding ways to help them get started with version control.

The more I think through it, the less convinced I am that I understand the non-technical use-case.

[jlong]

I'm not really sure what you mean about needing clearer use cases for this. Giving people the ability to share Sass extensions without making requirements on project structure or repository choice seems pretty straightforward:

• As a designer I want to share a Sass extension that I have on my website as a zip file.

However, I appreciate the desire to make the system as simple as possible. Perhaps a series of mockups walking us through a Sass manifest file approach with non-technical users in mind is in order? Would you be willing to tackle that?

Does anyone know if it's possible to create a Github repo under someone else's account programmatically? What would be amazing is to do something like this:

1. Create a new extension, select one:
    ( )  My project already exists on Github
    (o)  I'd like help setting up my project on Github
2. Authorize the Sass Registry to create a new project for you:
    [Login with GitHub]
3. Extension name
    Enter a name for your extension: [                  ]
4. Upload your files
    ( ) Browse for a zip file or Sass file
    (o) Enter a URL for the zip or Sass file
5. Let's create a Sass manifest file for you
    * Enter details...
6. Now let's add it to the registry
    [Publish extension]

[jlong]

Looks like it is possible to create a repo for a user:
http://developer.github.com/v3/repos/#create

[mirisuzanne]

Yep. Exactly that. :)

My question was really: what does it mean to be a non-technical sass developer? And, as follow-up, do we want to simply list links to sass files, or do we actually want to help create a better system for building, sharing, and maintaining extensions?

I love the idea of having forms that help walk you through setting up a maintainable extension. I'll start working on that idea.

[krisbulman]

I'm really interested in putting time into a registry and specifically a command-line utility to create/install/manage Sass extensions, components, etc. @jhardy's and @hatefulcrawdad's initial work feels like it's on the right path, although I don't know that there's much need much of a front-end UI ( or form solution) at all this early in the game, is there?

The manifest approach, requiring git for versions/tags really is the way to go when it comes to completely managing your packages in a project. It's easy to get off the ground, and would serve a large number of existing sass users, the front-end UI could come much later when the groundwork has been made on a command-line util and simple registry is in place.

Bower, Component & specifically a recent project by Anthony Short called Fonzie, prove to be pretty good solutions to package management, and it really seems like we could take a page from these as a basis for architectural discussion. A lightweight Sinatra server storing remote package locations is even a starter possibility.

reference links:
https://github.com/fonzie/fonzie
https://github.com/fonzie/server

Using this approach, a command-line util (gem) could initialize components locally, push them up to a repo, register them on a public server, provide a simple command-line search, and manage the components in the project using a config.rb for customization.

thoughts?

[jlong]

@krisbulman Would love to see what you could do on developing a command line interface for installing Sass plugins. Pretty convinced that we also need a frontend for this, but a kick-ass command-line interface is also in the cards. See issue #4. Feel free to jump in there to discuss further.

[carwin]

@krisbulman 👍

The registry and the actual CLI utility make more sense to me as separate entities.