@mintcanary , as we discussed today at the meeting.

consistent use of title case in value stories headers

Start Reading links to introduction not base of guide. /guide/en/introduction/ rather than /guide/en/

Sidebar should have donate, share, add a resource buttons.

• How do we do this?

From user story 2.2b - Hyperlinks to section headings in pages (and flagging of that in sphinx like way)

This is theme related.

As a User I want to see I can read a section (e.g. guide) in my language

As a User I want to know which languages I can read the guide (or maybe whole) handbook in so that I can see if my language is supported (and if not how I get it added (?))

As an Editor I want to easily add a new language to the list of languages that are supported so that it shows up as available

• government before civil society.
• wrap text nicely.

Part way there, but not quite working https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/menu.html#L20

Get in a first example value story so we can trial the setup and allow @mintcanary to do design

would it be worth having contribute pages as markdown (remember markdown can have html in it).

just a thought ...

It seems that Liquid leaves behind whitespace, even in statements that generate no output. This is most evident in the menu template, which has nested for loops that generate >50 kB of needless whitespace-only lines in every page.

It's not particularly important given modern broadband connections, but it would be nice to eliminate the whitespace during the generation process, preferably without fully minifying the output.

For non-technical editors

• Pages are written in markdown (or html) using jekyll cms (which is static page generator - the raw pages are rendered to output using the theme and served up statically)
• Markdown tutorial
  • Extras: footnotes, toc on page, how to do glossary and relative links generally
• We use jekyll - what’s the simplest explanation we can give of the metadata
  • See this tutorial

• check our flavour supports this.

As a config variable in _config.yml ...

• Analyse current handbook
  • Work out what is disappearing / merging
  • Work out what's staying
  • Work out where this redirects to
• implement (use jekyll redirect plugin we suggest)

This is something that I've mentioned a few times but I wanted to flag explicitly for discussion

This theme is now pretty nice and seems like it could become our standard theme for "handbook" or documentation sites. Concrete examples of immediate reuse include Data Patterns and OpenSpending community site.

What is the minimum needed to make this reusable for other (jekyll) sites? Do we need to split theme out to e.g. https://github.com/okfn/jekyll-template or can it stay here?

/cc @mintcanary

Add direct link to edit current page on Github.

• Write script
• Pull down latest translations - e.g. croation not in yet https://www.transifex.com/organization/okfn/dashboard/opendatahandbook
• Run script plus markdown conversion

Glossary terms are not interlinked - see http://new.opendatahandbook.org/glossary/en/ - cf glossary links discussion.

@pwalsh , didn't you said that you can do it?

atm i am preserving the special :term:... references that sphinx has in the markdown. I can auto convert these on the conversion from rst to markdown.

However, we could also keep something in and do some JS magic to convert these for readers to actually glossary references.

What's the benefit: it means that writers don't have to hard-code glossary html links - instead we can generate. It means we can move the glossary around. It means that glossary links work auto-magically in translation etc etc. It means we can change the name of a glossary item and not dig around to fix the source links.

Footer need to include the following items:

• Open definition button
• Terms of use (license) and privacy policy
• Contribute, donate and contact info
• Link to forum in footer - https://discuss.okfn.org/c/network-and-community/open-data-handbook

@mintcanary - this is for you. :-)

@mintcanary - as discussed, under edit, only in the guide section (including glossary)

@pwalsh , for your request - we need to look it at later.

v0.1

• Basic theme with front page and handbook page
• Migrate sample content from RST to markdown and jekyll

First pass at: http://okfnlabs.org/opendatahandbook-v2/en/what-is-open-data/

How can we add annotation support? Perhaps via annotateit or hypothesis.

This is probably low priority.

• Edit this page - both links are like buttons
• change to Help and Instructions for "contributing" text
• change Edit this page => Improve this page - more inviting

Section headings (e.g. value stories on value stories section) do not link back to their main section as one would expect

Missing all the credits from old guide (which should probably move out of there) - see bottom of http://new.opendatahandbook.org/guide/en/introduction/ (aside: we probably want to move that stuff out of guide to credits page).

Credit translators on credit page (?)

I get the following error when attempting to build locally

  Conversion error: Jekyll::Converters::Scss encountered an error converting 'css/main.scss'.
  Conversion error: undefined method `specificity' for [:not(.mm-subtitle)]:Array
jekyll 2.4.0 | Error:  undefined method `specificity' for [:not(.mm-subtitle)]:Array

/cc @mintcanary

• DNS
• CNAME

Suggest we use google custom search a la okfnlabs.org approach

Should look as follows:

• Home
• Open Data Guide
  • Introduction
  • Why Open Data
  • What is Open Data
  • How To Open Up Data
  • So I’ve Opened Up Some Data, Now What?
  • Glossary
  • Appendices
• Open Data Value Stories
• Open Data Resources
• Contribute
  • Contributing to the handbook
  • Adding a page to the guide
  • Editing a page in the guide
  • Translating the guide
  • Adding a glossary term
  • Translating the glossary
  • Markdown example
• Credits

@pwalsh , is it something I can fix?

Move this spreadsheet to the site - https://docs.google.com/a/okfn.org/spreadsheets/d/1MVVxdfZJyW-WRxKMSPC3h6A13CdkycrHFwRkJcV7Og4/edit#gid=0

We will update the spreadsheet from time to time, so this need to be taken under consideration.

Docs will live in contribute/index.md

Sections:

• How our site and pages work
  • jekyll and markdown tutorial - #6
  • pages stored in github and auto-published for us
    • Permissions and workflow (how pull requests work)
    • Requesting direct edit access to the main repo (joining the editor team) - email these folks
• Create a page
  • Log in
  • Creating a page in Github UI (need to be a repo owner?) - screenshot and highlight icon
  • Where to put pages … - if you want a page opendatahandbook.org/en/my-cool-new-page.html then create a page at /en/my-cool-page.md in the repo (note the .md extension indicating this is a markdown file)
  • Use this template
  • Save
  • (?) submit pull request
• Edit
  • Go to page on site or in github and hit edit (easier on site)
• optional power-user - you can clone the repo to your machine and edit files there!
  • clone the repo (or fork then clone)
  • commit
  • push
  • (submit pull request if not pushing direct)

Current state of play

Much of the site is translatable:

• Guide
• Glossary
• Value Stories

Some sections are not:

• Resources
• Credits

There are some challenges with managing translations in our use case. We've covered most of the territory, but some areas are left in need some work.

How it works

• We have a list of all languages, used for lookups that resolve a language key to a name: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L46
• Each section also has a language list, which represents that sections coverage. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L141
• Each section also has a helper key for activating language-specific logic. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L122
• Each content type has a default language of English. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L227
• Each content file also declares a language in front matter. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/guide/ja/how-to-open-up-data/index.md
• And then, of course, any given section that has translations is divided up by directories for each language: https://github.com/okfn/opendatahandbook-v2/tree/gh-pages/guide

All these elements are used in various places in the code, usually while looping over pages:

• All lists of content are language aware. For example: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_layouts/glossary.html#L8
• The TOC on the index page of the actual guides is built in a for loop (so additions to the guide, or changes to a chapter title, for example, are always picked up for a given language): https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/toc.html#L1
• Likewise, the main navigation is built via a similar (but simpler) loop: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/header.html#L57

What's working

• Any page that has one or many translated versions will display links to them
• Links in the main navigation are language aware (if I'm in the german guide, the links will be to other pages in the german guide)
• The "internal TOC" of all guides is language aware

What's not

• While the main navigation has language aware links, the title text is not language aware. As noted about, this is because it uses a rather naive loop, based on this data structure: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_config.yml#L186
  • Fixing this is totally possible, and will be something like this loop already working for internal guide TOC: https://github.com/okfn/opendatahandbook-v2/blob/gh-pages/_includes/toc.html#L1
  • The above TOC loop pushed my local build times from 7 seconds to around 30. Expect similar render time degradation when we deal with the main nav TOC in a similar fashion
• The website has no concept of state, so if a user is navigating, say, the german guide, and navigates to a language unaware page like credits - the user has moved back into english (all links from there will be "en" namespaced, and not "de"

• Contact editor and request translation be setup
• Editor copies across current guide content in english and records commit hash somewhere so we know what version they forked off
• Editor sends response and they can start translating

Ideas

• have a translated flag that is set to true when translation is 100% done. When not true we show a banner on page somewhere letting people know not translated and they can help out

• Establish secondary method
• Add to docs

Note: We should encourage using Github

• Create glossary page
• Add usage docs

[random]

• Last updated at top of page (just under author?)
• How do we implement
  • Write in with post-commit hook to jekyll frontmatter (nice as fixed)
  • Do via javascript by pulling commit info from github api

User story: As a Reader I want to know when an article was last updated so that I know how up to date it was

(dynamic) link to next page in the handbook.

I just forked and built the handbook for the first time. On first generation of the site locally, I see the following errors from the sass compiler:

WARNING: The $display argument will be deprecated in future versions in favor of the display(){...} mixin.
         on line 11 of /Users/paulwalsh/code/projects/opendatahandbook/_sass/neat/settings/_disable-warnings.scss, in `-neat-warn'
         from line 39 of /Users/paulwalsh/code/projects/opendatahandbook/_sass/neat/grid/_row.scss, in `row'
         from line 931 of an unknown file, in `@content'
         from line 62 of /Users/paulwalsh/code/projects/opendatahandbook/_sass/neat/grid/_media.scss, in `media'
         from line 929 of an unknown file

WARNING: Resetting $display will be deprecated in future versions in favor of the display(){...} mixin.
         on line 11 of /Users/paulwalsh/code/projects/opendatahandbook/_sass/neat/settings/_disable-warnings.scss, in `-neat-warn'
         from line 64 of /Users/paulwalsh/code/projects/opendatahandbook/_sass/neat/grid/_to-deprecate.scss, in `reset-display'
         from line 984 of an unknown file, in `@content'
         from line 62 of /Users/paulwalsh/code/projects/opendatahandbook/_sass/neat/grid/_media.scss, in `media'
         from line 980 of an unknown file

any ideas?

Nice link (maybe follows you down the page) for editing the page that takes you directly to github source (or, maybe, better prose.io)