18f / hub Goto Github PK

DEPRECATED: Documentation hub for the 18F team

Home Page: https://github.com/18F/handbook

License: Other

Ruby 15.74% HTML 7.00% CSS 10.84% JavaScript 64.82% Shell 0.78% Python 0.53% Nginx 0.29%

hub's Introduction

18F Hub

The 18F Hub is a Jekyll-based documentation platform that aims to help 18F and other development teams organize and easily share their information, and to enable easy exploration of the connections between team members, projects, and skill sets. It aims to serve as the go-to place for all of a team's working information, whether that information is integrated into the Hub directly or provided as links to other sources. It also serves as a lightweight tool that other teams can experiment with and deploy with a minimum of setup.

The internal 18F Hub is hosted at https://hub.18f.us/ and the public Hub staging area is hosted at https://hub.18f.us/hub.

See the 18F blog post announcing the Hub for more details about the vision behind the Hub and the goals it aims to achieve.

The main Git repository is https://github.com/18F/hub and the primary maintainer (for now) is @mbland. The goal is to eventually hand ownership over to the Documentation Working Group, or to the 18F team as a whole.

Generating the site/hosting locally

It takes less than a minute to set up a hands-on demo, which we hope will inspire other teams to develop their own Hubs, publish snippets, and organize working groups/guilds/grouplets.

You will need Ruby version 2.1.5 or greater. To run your own local instance at http://localhost:4000:

$ git clone [email protected]:18F/hub.git
$ cd hub

# Only 18F team members need run this:
$ ./go init

$ ./go serve

See the "Hub 101" docs either in this repository, served locally, or on the 18F Public Hub for details and tips on how to set up and work with the Hub development environment.

Contributing

Fork the repo ( https://github.com/18F/hub/fork ). If you're an 18F team member, you'll likely find it easier to clone the repo instead of forking it (git clone --recursive [email protected]:18F/hub.git). The recursive clone ensures that you'll grab the contents of private submodules.
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Feel free to ping @mbland with any questions you may have, especially if the current documentation should've addressed your needs, but didn't.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

hub's People

Contributors

Stargazers

Watchers

hub's Issues

go serve command fails without submodules

When running
./go serve

after running
./go init

but before initializing the submodules, I get the following:

canonicalizer.rb:90:inblock in sort_by_last_name!': undefined method downcase' for nil:NilClass (NoMethodError)

It works with the submodules.

Visual Indication of Public Hub vs. Internal Hub

@meiqimichelle @elainekamlley @gboone @leahbannon

As we work on making the Hub both a resource for ourselves from the data-private side, we are also making some of it available to the public. From an internal perspective - should we have different designs for each instance so we know which version we're looking at?

Do we need to have some indications on the public hub that this is a public version of things and that some of the items have been redacted? For example, should we call it "18F Public Hub"?

Migrate bio info from Google Wiki to hub

Add personal bio info that is currently in our Google Wiki to Hub person pages.

Specialties sort order should ignore case

On the specialties page (which is awesome, btw) the specialties are sorted alphabetically, which puts the Upper Cased ones first. Either the sort order should be case-insensitive, or we should enforce case in people's specialities.

Create guideline layout

The thought:

the Hub backend repos(s) can host all our guidelines (public and private) in markdown
the internal Hub frontend needs to layout to consume all of these
those markdown files can then also feed whatever else we want to create with them via the Hub API

This issue is to create the layout so we can start hosting our guidelines all in one place. At a very simplistic level, this layout needs:

solid typography paragraphs, lists and headings
nav for subsections

Discuss.

Search only allows nine characters

Works pretty well up to nine characters, but completely stops showing results as of the tenth.

cc: @afeld

File update: correspondence symbol = org code

On "18F Structure" page, update Where Am I? to reflect:

"org code" is the same thing as "correspondence symbol"

508 - Links should be unique

Read all links, learn more link

data file breaking?

Haven't learned enough about what data is supposed to go where and how so might be off on this, but by chance, are apostrophes breaking the data formatting somehow in the team.yml file?

The github coloration just caught my eye and made me concerned. Notice the all read starting at the apostrophe at the end of aaron's bit and going through to the end of Alison's bit.

Add alpha bug to top of hub

A la:

add 18f org chart to /hub

When it's at a good point for it, it'd be great to add to /hub.

@quepol - do you want to ping here when it's to that point? Alternatively, if you're game to post the remaining issues, @mbland or I can keep an eye and check in if it looks like they are addressed.

Separate plugin layouts from other layouts

The layouts in _layouts used by plugins should be separated into _plugins/layouts, leaving _layouts with only layouts used directly by pages in pages.

cc: @meiqimichelle

Improve automation of adding new team members

Right now, the authentication list used to configure access to the Hub is automatically generated by the auth.rb plugin given information in _data/private/team.yml. However, updates to team.yml do not yet trigger an automated deployment to https://hub.18f.us/ and restart of the google_auth_proxy that controls access.

Add office location API

Once #108 is integrated, as noted in that PR, the longer-term ideal would be to replace the locations array in assets/js/map.js with a call to /api/locations (or /api/locations.json?).

cc: @shawnbot @msecret

508 - Search field is missing label

Search needs a 'clear' option

Yo know, ex-out and all :)

Change title of public hub

Current is the same as internal hub, "18F Internal Team Information Hub"

First page load takes a very long time

Per discussion with @mbland, I ran into a problem where these two links:

have dramatically different load times. The former took over a minute to load (enough that I closed the browser tab twice and reloaded it thinking I had some issue on my end); the latter popped up instantly.

I can't really evaluate how long they take in the shell because both are authenticated, although I could probably shim something up to do that if someone would like.

Mike thinks it may be my connection. At the moment, I have pretty substantially reduced bandwidth (between 10 and 20 kbyte/s, so 1.5-2.8x dialup), which hasn't been an issue, like, at all, for working on github/over ssh.

The reason I mention this is it seems problematic to house policy documents in a place that is hard to get to.

The "hub" pages are as fast as github pages after that initial, very-long pageload.

Fix username text alignment in nav

I tried just .auth-include img { vertical-align: bottom; }, but I think it needs more than that.

text typed in search box should be black

Too hard to see!

/cc @meiqimichelle

508 - Autocomplete doesn't have proper aria attributes

automate snippet collection and publishing

Right now the process works. Reliably. We can automate the collection and processing of the snippets using the Google Data APIs and App Engine for scheduled jobs.

Move staff skills from spreadsheet to Hub

When ready :)

cc @kaitlin

Improve API implementation

Per @gboone: Very-Simple-API

Basic idea is, a lot of the current _plugins/api.rb implementation can be stripped out by relying on a stripped-down layout that just pipes data through the jsonify filter.

MyUSA Authentication

In order to potentially pitch the Hub to groups that don't use Google-managed domains, we need to investigate how we could potentially use MyUSA for Hub authentication.

cc: @yozlet @afeld @dlapiduz @cpapazian

Remove 'internal guidelines' sub-head from guidelines page

Unnecessary division between the parts of the page.

As a contributor, I would like to see analytics on what pages are most visited...

then I might spend more time making those great

508 - Visual Focus is lost on 'your' profile link

Visible focus lost between 'new to 18f' and search

Scalable data model

In order to support adding multiple teams to a single Hub, we need to rethink _data/private/data-private somewhat.

Already there's the idea that we should split the projects.yml file into separate files. We should probably do the same for team.yml, pif_team.yml, and potentially all of the data files that are basically collections/Arrays of Hashes.

There's also the notion of supporting multiple teams in a single Hub instance. Will start thinking about this; open to ideas.

cc: @meiqimichelle @afeld @gboone @elainekamlley

Address client-side search issues

The issues @msecret raised in #80 still need to be addressed.

Also, it appears the search box only allows nine characters before the search function fails. We should understand why this is happening and address it if possible.

cc: @meiqimichelle @gboone @elainekamlley @brethauer

508 - Skip nav is needed

Fix nested list styles

#81 was a quick-fix for unordered list items nested two levels deep, but nested lists beyond that aren't indented properly. Since I haven't been touching any CSS besides assets/_sass/_hub.scss, I need folks with deeper CSS knowledge than I to help fix this.

cc: @afeld @meiqimichelle

508 - Profile image missing alt attribute

add guilds, working groups

I'm not sure of the best way to fit them in, but imagine it'd be helpful to incorporate them.

508 - Placeholder text fails color contrast

New navigation structure

Per http://mrl.li/m1gyBPdV

Google Analytics for hub.18f.us are reporting to the 18f.gsa.gov profile

I think this isn't what's expected:

Add better nav for team-related information

There are many ways to slice-and-dice our team info:

by location
by skill
by name

In the old layout, this was clear. In the new layout, it is not obvious.

Add link to GitHub activity as snippet aid

Migrated from 18F/hub-original#26. From original issue:

Per @afeld's idea:

https://github.com/search?utf8=%E2%9C%93&q=user%3A18f+created%3A%222014-11-22+..+2014-11-30%22+author%3AUSERNAME&type=Issues&ref=searchresults

Add categories for How To

Add intro to hub

Current page does not describe what it is or what people will find there. Add something to gives public a reason to care :)

(I'm mostly thinking about the public version on this -- although would likely be helpful on private version as well)

Set up a continuous integration service

As I promised @afeld in #1, I'll set up a CI service to ensure the site builds successfully with each new change. I've been advised by devops folks to try Snap-CI.

Implement automated deployment of public Hub

Working with @gboone, the automated deployment environment is largely ready to go, but a couple of items need doing:

add mbland's key to the 'site' user on 18f.gsa.gov
update the 18f.gsa.gov nginx config to respond to the /hub/deploy webhook on port 4002
fab start --set branch=production-public

Add /howto section

Migrating from 18F/hub-original#23. From the original: We'll start adding some helpful docs to /howto, the first of which being how to add/update docs in /howto via different git clients!

cc @blacktm @jtag @meiqimichelle @afeld @gboone

Search bar should clear on back/forward

Seems like now if you search for something, go to it, and then hit 'back', the search bar is still populated with the original search (which right now means that the page content is blank because of a separate issue).

Changes/additions to New Hire Pro Tips

While we're transitioning the info from the New Hire Pro Tips doc over to the hub, please use this issue to record and edits or additions you'd like to make. That way, they won't get lost in the cracks! You can also open a new issue in this repo if you like -- whatever works for you :) Thanks!

newsclips - where to fit in

I've been keeping a list of 18F news clips in /team-ops, but can move them here. Any preference as to where I put them? I can forklift it as a page onto 18f.gsa.gov/hub easily enough but @mbland, do you have something else in mind?

@OriHoffer, @gboone - any thoughts?

[This is in support of https://github.com/18F/hub-pages-private/issues/3]