The help pages are too hard to update

garethrees commented 8 years ago

The current way of modifying the help pages means you have to have a pretty deep understanding of git, GitHub, HTML and a little Rails.

The process is fine if you're an Alaveteli core developer, but I recently spent an hour on a hangout with a partner resolving merge conflicts to some help page modifications. It shouldn't be this difficult.

We briefly chatted about this in standup. Here are some off-the-cuff ideas:

Just email them the current set of pages and apply the diff to the repo ourselves
Some sort of built-in WYSIWYG editor
A separate repository of markdown files that get pulled in to the app and converted at deploy-time
A separate app that gets mounted (e.g. as a rack app) or redirected to which has specific features for editing help pages (WYSIWYG, decluttering the main app code).

I don't want to latch on to a specific idea at this stage – I think we really need to talk to partners about how they'd actually prefer to do this – but I do quite like the thought of plain-text files, rather than more stuff-in-a-database.

garethrees commented 8 years ago

I have a bit of experience with doing the WYSIWYG stuff; here's a dump from a ~~yet-to-be-published~~ blog post:

Pages

For slower moving content – i.e. content that only gets updated a few times a year – Thoughtbot's HighVoltage gem was used. To add a page, the developer simply needs to add a new view, stylesheet and javascript file in the appropriate pages directory.

pages-directory-structure

This format was primarily chosen so that the developer has full control over the markup and styling. The previous iteration of cardiffstudents stored full page layouts in the database which lead to a rigid design structure.

To automate editing content on these 'static' pages, Mercury Editor has been added as a beta feature. This still allows the developer full control over markup and styling, but allows them to define editable regions of text. A simple Rails helper is used to find the correct text from the database. Placeholder text is automatically generated for development use.

page-edit

Setting Editable Areas

<div id="what-is-the-agm" class="mercury-region" data-type="editable">
  <%= content_for_area('your-union', 'what-is-the-agm') %>
</div>

Retrieving Content

module PagesHelper
  def content_for_area(content, area)
    area_content = Content.for_area(content, area)
    raw area_content.body ? area_content : "Lorem ipsum dolor sit amet"
  end
end

class Content < ActiveRecord::Base
  def self.for_area(page_name, area)
    self.find_all_by_page_name_and_area(page_name, area).last
  end
end

garethrees commented 8 years ago

https://github.com/lektor/lektor

crowbot commented 8 years ago

http://prose.io/ may be relevant here - in use in the parliaments team

garethrees commented 8 years ago

Similar to prose https://forestry.io/

garethrees commented 9 months ago

Just dumping a lightly edited slack comment here to link up a few related issues:

Getting towards this with Notes, and via Topic Pages the generic Category system (for the sidebar), and hopefully a better editing capability, to culminate, maybe, in a knowledge base. That still doesn’t fix the problem of wanting to provide some stuff that we write as defaults and figuring out how to handle when we ship updates to that but the reuser has changed that section.

mysociety / alaveteli