search

18F / hub

DEPRECATED: Documentation hub for the 18F team
https://github.com/18F/handbook
Other
46 stars 33 forks source link

Finish Jekyll site for handbook #505

Closed mtorres253 closed 8 years ago

mtorres253 commented 8 years ago

Right now we have the site in jekyll format, this story is to add all of the content so that we have something we can host (wherever we decide to host it)

Let's start on this now and add stories as we get through some of this.

  1. Finish existing jekyll site
  2. Add breadcrumbs
  3. Make responsive
  4. Toggle table of contents

Acceptance Criteria: Have a first pass of the handbook to show to team at the all hands.

andrewmaier commented 8 years ago

What do we want to do about external content? We won't be able to style it as we've presently arranged things.

cloud2

mtorres253 commented 8 years ago

If the external content is hosted somewhere, we can just open a new tab containing that content. We can see if we can clean that up later, but I don't know of any elegant solutions to that problem

andrewmaier commented 8 years ago

Would be nice to have an API to get that content directly!

melodykramer commented 8 years ago

We could also create pages within the Handbook that then link to those resources. I realize this is not elegant, but then the page would retain other elements, like breadcrumbs and related links.....

melodykramer commented 8 years ago

Sharing feedback from various folks at 18F who saw the prototype yesterday:

  1. “table of contents” means two separate things on the same page. we should change that.
  2. the in-page contents are buried a bit. which is fine, in general, but we might want a visual cue over the table of basics, perhaps in the form of an H2 like Basics or Overview or something. that suggests more that there are other sub-sections. right now it looks a bit like that table is all the content there is under Chicago.
  3. i’d love to see just a bit more visual distinction around the screen shots.
  4. How do I… and Amenities both contain info exclusively related to access and/or transportation. this is Chicago-specific, but i’d still consider grouping those elsewhere or retitling if possible.
  5. this is a long-term issue, not worth addressing quickly at all, but it might be worth grouping the in-page contents at some point and giving them a bit of hierarchy. there’s ​​so much​​ there that the list gets a bit unwieldy.

I also want there to be a button on each page “There is incorrect information on this page” and another one that says “I want to add something to this page"

I feel a little confused by the overall navigation - it's jarring to have to open that table of contents and scroll down to find the next section I'm looking for. I wish it took me through the content more fluidly. Also didn't realize right away what I was looking at - I need some orientation to tell me I'm in the 18F handbook. But the structure and content of the individual pages is :thumbsup:

Looks nice! I tested some of the links and they appear to work. One thought I would have would be how can we minimize the number of items in the table of contents but still get people to what they want every time?

I miss the header delineation a bit, as it helped my brain process where the content started. But that could be an individual preference."

"For me, both the first, and second level of indentation in the sidebar being letters is a bit messy."

Why hide the sidebar

I also got a bit lost in the length/linearity of the page — the TOC is ​​so long​​ that it doesn’t feel comprehensible on initial read. I suspect some minor content/header edits could help tighten that up and make it feel less intense

andrewmaier commented 8 years ago

So my todo list based on conversations with @mbland, @melodykramer, and @mtorres253 is:

melodykramer commented 8 years ago

Related content might be nice too - happy to add tags, if that's something that would be useful.

melodykramer commented 8 years ago

Also worth noting the 10 top trafficked handbook pages so far - a LOT of "How do I do this thing" - which makes me think (for a later iteration) having a design specifically for instructions would be useful.

screen shot 2016-01-07 at 3 50 04 pm

mtorres253 commented 8 years ago

This story is getting a bit big. Let's break this out into smaller tasks and sequence.

andrewmaier commented 8 years ago

From @brittag

  1. I’d remove the Slack logos! We just happen to use a specific team chat vendor since it works for our purposes; we’re not dedicated to Slack in specific.
  2. The ToC (I mean the floating toc at right) wouldn’t really work for the way I use documents - the Wikipedia style of a short ToC after the intro makes sense to me.
  3. and right now you have two things labeled ToC - the document-specific one and the general handbook one. better to give them different names.
  4. Why not leave the left handbook index open by default?
mtorres253 commented 8 years ago

@andrewmaier @melodykramer This story was to get a simple version of the handbook up in a jekyll site so we could test with users. Looks like that has happened, so I think this can be closed? We can assess the user feedback and iterate in future stories.

andrewmaier commented 8 years ago

@mtorres253 Sounds good.

mtorres253 commented 8 years ago

Great @andrewmaier Is there a link to the jekyll site that you can attach to this story?

andrewmaier commented 8 years ago

@mtorres253 Here's the branch: https://github.com/18f/handbook/tree/design-assets

We could ask @mbland about hosting it on 18f-staging?

mbland commented 8 years ago

Push to an 18f-pages-staging branch and it will appear as https://pages-staging.18f.gov/handbook/.

andrewmaier commented 8 years ago

@mbland And that doesn't make it public, right? :)