Move the Handbook off WordPress and onto an HTML site

[melindaburgess]

Since we are now collaborating via GitHub, it would be great if people could submit changes and add updates directly to the Handbook via Pull Requests.

We need someone to help us move the Handbook off our WordPress site and put it in HTML.

[bengm]

Sounds smart. Clarifying questions:

1. Is the idea to pull just the handbook bit out of the web site, or convert the entire agilegovleaders.org web site?
2. Are you thinking of keeping the same styling as the main site, or making the Handbook more of a standalone reference? (i.e. 18F has the main site and various guides.

[melindaburgess]

Great questions, @bengm - Clarifying answers:

1. Once upon a time, when the Handbook was first launched about 18 months ago, it was a separate site (HTML) and we referenced/linked to it in our AGL website, which has always been WP. (It did have similar styling as the AGL site and most folks might not have realized it was a separate site. We kept them very integrated). When I took over management of the website we moved the Handbook over because I'm not a coder. It also seemed more streamlined at the time.
2. The Handbook remains the most visited page on our site, so it is obviously helpful to people. Given that, we've been thinking that a brush-up of the Handbook is overdue. We'd love to keep it fresh and include all the new interesting things that have been going on in agile gov recently.
3. Simultaneously, we've been doing this re-structuring where we've invited much more open collaboration from other leaders in agile government, and moving our work to GitHub. We realized it made sense to move the Handbook to where anyone could easily submit changes and updates, inviting a fresh stream of brilliance at all times.
4. We need someone who knows about such things to take this project idea and run with it! (Maybe also give me some mini-lessons in HTML along the way so I can become a better administrator going forward) :)

[bengm]

I can certainly help converting the handbook to a github-pages (Jekyll/HTML) site. (Jekyll being the normal way to create a github-based site, and provides flexibility for little-to-no-html in maintaining content.) It probably makes sense to have a discussion to iron out a few things, like:

• Anticipated growth in content volume of the handbook (if applicable)
• Design direction (start with replicating what exists vs. a reference book/docs style)
• Intro to the Jekyll way of editing content (not quite as simple as Wordpress, but almost)
• URL: i.e. handbook.agilegovleaders.org vs. www.agilegovleaders.org/handbook
• Other small details, like who would update DNS, how we'd handle the old page/URL.

[melindaburgess]

Excellent thoughts, and that sounds like a great plan.

@lukefretwell - As the person who formerly administered the page handbook.agilegovleaders.org and who has the most knowledge as to its current status and what might need to be ironed out regarding the above plan, would you be able to jump in a meeting sometime to help with handoff?

[melindaburgess]

@elizabethraley - You would probably also want to be involved in this discussion, as you and I could start to learn how to admin using Jekyll / github

[lukefretwell]

@bengm thank you for helping out with this.

Comments:

• Yes, 18F template would be ideal/perfect. I really like how they used it here: https://standards.usa.gov/.
• As far as branding, I think the fonts are great, but if we could use the AGL red that would be great.
• @grugnog can handle the DNS issue. @melindaburgess, we'll need to do a simple redirect in WordPress from /handbook to the handbook.agilegovleaders.org URL once it's up.

[bengm]

Update: I've done some investigation, forking the 18F guides template and setting up a site. There are some limitations with it, as it is pretty heavily tailored to 18F specifically, and doesn't play well with github pages.

Next steps:

• Start with CFPB DOCter, what 18f guides started with, which is more straightforward to customize
• Discuss design ideas and integration - a call is probably warranted

[melindaburgess]

Thanks for the update @bengm . I am hoping you and @lukefretwell can connect about this. I would be interested in being on the call too, for learning purposes.

[melindaburgess]

Also, @bengm - I wanted to add that I've been updating the Handbook and ended up making pretty significant changes to the content. I don't know how that figures into the migration process, but wanted to let you know. All the updated content can be found here: https://docs.google.com/document/d/1ZB4FtM_SucmuLHC8HbaXbA9bOWidxygmultb3r5mSvI/edit#

[bengm]

I've made a bit of progress. Slogging through the wordpress HTML was a bit rougher than expected, but I think we're over the hump there. You can see the live preview site and the repo.

What is good:

• The site uses the AGL template for consistent styling
• Pulls sections from _sections folder, providing a fairly painless 'novice' editing experience for content
• I think the header/footer type links work, but haven't really tested

What still needs fixed (fortunately these are pretty straightforward):

• Lots of padding issues to refine the style, particularly between sections
• Need to add option for black content background
• Need to add quick in-page nav links to try that out
• Note: the content is still partial and based on the old content, so it is there for the proof of concept, but would need to be update expanded

[bengm]

@melindaburgess I fixed the major things above. It is ready for a solid review. Here's what I suggest:

1. Look at the live preview site side-by-side with the current handbook and provide any comments. There are a couple things I'm not sure about: a) the header area, we can just replicate the current site so it acts like part of the larger site; or b) delete it and start with the white-on-red 'handbook' title.
2. Look at the repo. Using the readme information, try editing one section; and adding a new section. This will give a feel for how good the readme documentation is, and how friendly the github-pages/markdown model is.

With that feedback, we should be able to wrap it up. Then just need the sysadmin type help to get this repo under agl's org, and reroute the domain to this version.

[melindaburgess]

@bengm Thanks very much for your help and clear information. I will prioritize this and be in touch.

[melindaburgess]

@bengm I'm playing around with the Handbook now. Re: the header, my only concern is that I want people to be able to easily navigate back into the AGL site. So I guess we should go with (a), and let it replicate the current site.

[melindaburgess]

@bengm Comparing the first few sections. I noticed the first two (About) and (History) are 100% width on the text, while (Manifesto) and (Principles) are about 2/3 width. I do prefer the former, but we should probably have consistency either way.

Also I tried to center the video Gov.UK but not sure if I did it right. It's kind of tricky that I can't see an ACTUAL preview of how it would appear live, before submitting a pull request.

[melindaburgess]

@bengm I think for the navigation headers, they should be (ABOUT) (BEST PRACTICES) (RESOURCES) and (TOPICS)... once we have created all those sections.

[bengm]

@melindaburgess Thanks. I'll work on fixing a couple of these little things. Note on the 2/3 width... on the current handbook, it is also offset/indented by 1/3 on the left for those more styled sections. I can replicate that for now.

[bengm]

@melindaburgess I've made the styling & template changes above. I also added a note to the readme on the issue w/ the roles section. It seems once you put in HTML, you have to stick with it (markdown won't be processed within the HTML).

[melindaburgess]

@bengm I have tried adding more sections and made some pull requests. One of the sections I added (Terms) is acting funny on me - I couldn't get a good preview of it and wonder if I did something wrong. At your convenience maybe you can take a look.

[bengm]

@melindaburgess I checked on the Terms section - it was a small thing, the file name didn't have an extension (I changed to Terms.md and all seems well now)

[melindaburgess]

@bengm Thank you!!

[bengm]

@melindaburgess One quick followup on ability to preview changes - If you go to your fork of the repo, and hit settings near top-right, then choose to enable github pages.... you should be able to see it "live" at melindaburgess.github.io/agl-hb

Here's that portion of my repo's settings as an example...

[melindaburgess]

Thanks, @bengm - that's super helpful

[melindaburgess]

@bengm I tried to find the "Minima" theme that you seem to be using, but I don't see it. My fork is viewable but it looks wonky. :)

[melindaburgess]

If you want to accept my latest round of pull requests, I'd be interested to see them. They don't seem to be showing up on my fork either.

[bengm]

@melindaburgess I don't think the theme matters... I'll be curious to try and fork it elsewhere (maybe our STSI company acct) and see how it works.

I did accept your PRs. The 'agile projects' section was off slightly - some easy-to-make errors with the yaml header formatting (missing the "---" at the end) and the youtube video ID included the "v=" at the beginning, but it shouldn't. The rest seems like it shows up ok.