User guide in docs/guide, shown in the app under Help

- 16 Markdown pages covering every area for pilots, owners, mechanics
  and admins, readable on GitHub
- /help renders them with a page list; links between pages work in both
  places; only listed pages can be opened
- The electronic records instructions (AC 120-78B user instructions) are
  now the guide's records page, also used as the procedures appendix
- Help link in the main menu

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-07 13:40:09 -05:00
1 parent 761f381679
commit fe3fba1736
28 files changed
+599 -32

No files matched your search

+4
View File
@@ -130,6 +130,10 @@
.markdown table { display: block; max-width: 100%; overflow-x: auto; border-collapse: collapse; font-size: 0.85em; }
.markdown th, .markdown td { border: 1px solid var(--color-slate-200); padding: 0.25rem 0.5rem; text-align: left; }
.markdown th { background: var(--color-slate-50); font-weight: 600; }
.markdown.guide { line-height: 1.6; }
.markdown.guide h1 { font-size: 1.5rem; font-weight: 700; }
.markdown.guide h2 { font-size: 1.15rem; margin-top: 1.25em; }
.markdown.guide h3 { margin-top: 1em; }
}
/* ---- Phones ---------------------------------------------------------- */
+6 -2
View File
@@ -1,4 +1,8 @@
# User instructions for electronic records and signatures (AC 120-78B 2.2.12, 3.2.9).
# The user guide (docs/guide), including the instructions for electronic
# records and signatures (AC 120-78B 2.2.12, 3.2.9).
class HelpController < ApplicationController
def records; end
def show
@page = HelpGuide.find(params[:page] || "README") or raise ActionController::RoutingError, "Not found"
@pages = HelpGuide.pages
end
end
+10
View File
@@ -0,0 +1,10 @@
module HelpHelper
def help_page_url_for(slug, anchor = nil)
slug == "README" ? help_path(anchor: anchor) : help_page_path(slug, anchor: anchor)
end
def guide_html(page, links: true, title: true)
html = HelpGuide.html(page, title: title, link: (links ? method(:help_page_url_for) : nil))
tag.div(html.html_safe, class: "markdown guide") # rubocop:disable Rails/OutputSafety -- sanitized in HelpGuide
end
end
+39
View File
@@ -0,0 +1,39 @@
# The user guide: Markdown files in docs/guide (readable on GitHub too),
# shown in the app under /help. Only the pages listed here can be opened.
class HelpGuide
DIR = Rails.root.join("docs/guide")
ORDER = %w[README getting-started profile aircraft flights squawks oil-and-fuel components logbook records
inspections ads documents major-records sharing administration].freeze
OPTIONS = {
parse: { smart: true },
render: { hardbreaks: false, unsafe: false },
extension: { strikethrough: true, tagfilter: true, table: true, autolink: true, header_ids: "" }
}.freeze
TAGS = %w[p br strong em del a ul ol li blockquote code pre h1 h2 h3 h4 hr table thead tbody tr th td].freeze
ATTRIBUTES = %w[href id align].freeze
Page = Data.define(:slug, :title, :markdown)
def self.pages = ORDER.filter_map { find(_1) }
def self.find(slug)
return unless ORDER.include?(slug.to_s)
path = DIR.join("#{slug}.md")
return unless path.file?
markdown = path.read
Page.new(slug: slug.to_s, title: markdown[/\A# (.+)$/, 1] || slug.to_s.titleize, markdown: markdown)
end
# Sanitized HTML. Links to other guide pages ("records.md#mistakes") go
# through `link` (slug, anchor) -> URL, or become plain text when nil.
def self.html(page, link:, title: true)
source = title ? page.markdown : page.markdown.sub(/\A# .+\n+/, "")
html = Commonmarker.to_html(source, options: OPTIONS, plugins: { syntax_highlighter: nil })
html = Rails::HTML5::SafeListSanitizer.new.sanitize(html, tags: TAGS, attributes: ATTRIBUTES)
html.gsub(%r{<a href="([a-z-]+|README)\.md(?:#([a-z0-9-]+))?">(.*?)</a>}m) do
slug, anchor, text = $1, $2, $3
next text unless link && ORDER.include?(slug)
%(<a href="#{ERB::Util.h(link.call(slug, anchor))}">#{text}</a>)
end
end
end
@@ -97,7 +97,7 @@
<h2 class="<%= h2 %>">13. User instructions and training</h2>
<p class="<%= p_ %>">Every user who keeps or signs records reads these instructions (also in the system under “How electronic records work”) before signing (2.2.12, 3.2.9).</p>
<div class="mt-2 rounded border border-slate-200 p-3"><%= render "help/records_content" %></div>
<div class="mt-2 rounded border border-slate-200 p-3"><%= guide_html(HelpGuide.find("records"), links: false, title: false) %></div>
<% if policy.additional_procedures.present? %>
<h2 class="<%= h2 %>">14. Additional procedures</h2>
-21
View File
@@ -1,21 +0,0 @@
<%# User instructions for electronic records (also an appendix of the procedures document). %>
<div class="space-y-3 text-sm leading-relaxed">
<h3 class="font-semibold">Writing an entry</h3>
<p>On the aircraft's Logbook tab, choose <strong>+ New Entry</strong>. Give the date, the logbook (aircraft, engine, propeller), the airframe total time, and what was done; for an engine or propeller entry pick the component (its times fill in) and tick any sub-components. A template can start the wording. An entry isn't a signed record until it's signed.</p>
<h3 class="font-semibold">Signing</h3>
<ol class="list-decimal space-y-1 pl-5">
<li>Add your certificate (kind and number) once, on your profile.</li>
<li>Open the entry and choose <strong>Sign</strong>. Read the entry as shown: your signature covers exactly that.</li>
<li>Pick the certificate you're signing with. The statement you'll certify is shown with it (return to service, or the inspection statement).</li>
<li>Re-enter your password, or sign in again with single sign-on, tick the confirmation and choose <strong>Sign entry</strong>. You'll see a confirmation and get an email.</li>
</ol>
<p>Never share your password or let someone else sign while you're signed in: a signature is yours alone. If you think someone has, tell the administrator straight away.</p>
<h3 class="font-semibold">Mistakes</h3>
<p>A signed entry can't be edited or deleted. Open it and choose <strong>Correct this entry</strong>: a new entry starts from the original; fix it, save, and sign it. The original stays, marked “Superseded by a correction”.</p>
<h3 class="font-semibold">Someone else did the work</h3>
<p>The owner can choose <strong>Ask someone to sign</strong> on the entry: the mechanic gets a one-time email link, signs in or creates their own account, adds their certificate and signs. If they prefer paper, print the entry (<strong>Print for logbook</strong>), have it signed in ink, and keep the paper with the logbooks (scan it into Documents).</p>
<h3 class="font-semibold">Checking a record</h3>
<p>A signed entry shows who certified it, with which certificate, when (UTC), what they certified, and its status. <strong>Valid</strong> means nothing has changed since signing. The fingerprint (a SHA-256 of the entry) is printed on paper copies so a copy can be matched to the record. Every change to any record is kept under <strong>Activity → Record history</strong>.</p>
<h3 class="font-semibold">If the system is down</h3>
<p>Make the entry on paper and sign it in ink. When the system is back, add the entry and scan the signed paper into Documents; the paper itself stays with the logbooks and remains the signed record for that entry.</p>
</div>
-6
View File
@@ -1,6 +0,0 @@
<% content_for :title, "How electronic records work" %>
<section class="card card-body max-w-3xl">
<h1 class="text-2xl font-bold">How electronic records work</h1>
<p class="mb-4 mt-1 text-sm text-slate-600">Instructions for everyone who keeps or signs maintenance records here.</p>
<%= render "help/records_content" %>
</section>
+14
View File
@@ -0,0 +1,14 @@
<% content_for :title, "Help: #{@page.title}" %>
<div class="grid gap-5 lg:grid-cols-[14rem_1fr]">
<nav aria-label="Help pages" class="lg:order-none">
<details class="card lg:hidden">
<summary class="card-header cursor-pointer"><span class="card-title">Help: <%= @page.title %></span></summary>
<ul class="p-2 text-sm"><% @pages.each do |p| %><li><%= link_to p.title, help_page_url_for(p.slug), class: [ "block rounded px-3 py-2 hover:bg-slate-100", ("bg-slate-100 font-semibold text-sky-700" if p == @page) ] %></li><% end %></ul>
</details>
<ul class="sticky top-4 hidden space-y-0.5 text-sm lg:block">
<% @pages.each do |p| %><li><%= link_to p.title, help_page_url_for(p.slug), class: [ "block rounded px-3 py-1.5 hover:bg-slate-100", ("bg-slate-100 font-semibold text-sky-700" if p == @page) ],
aria: { current: (p == @page ? "page" : nil) } %></li><% end %>
</ul>
</nav>
<article class="card card-body min-w-0 max-w-3xl"><%= guide_html(@page) %></article>
</div>
+2
View File
@@ -35,6 +35,7 @@
<div class="absolute right-0 z-30 mt-2 w-56 rounded-md bg-surface py-1 text-slate-700 shadow-lg ring-1 ring-slate-200">
<p class="truncate px-4 pt-2 pb-1 text-xs text-slate-500"><%= current_user.email_address %></p>
<%= link_to "Profile", edit_profile_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
<%= link_to "Help", help_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
<% if current_user.admin? %>
<p class="border-t border-slate-100 px-4 pt-2 pb-1 text-xs font-semibold text-slate-500">Admin</p>
<% [ [ "Users", admin_users_path ], [ "Component Types", admin_component_types_path ], [ "Airports", admin_airports_path ], [ "Logbook Templates", admin_logbook_templates_path ], [ "Settings", edit_admin_settings_path ], [ "Recordkeeping Procedures", admin_procedures_path ], [ "Records Audits", admin_audits_path ], [ "About", admin_about_path ] ].each do |label, path| %>
@@ -59,6 +60,7 @@
</div>
</details>
<% end %>
<%= link_to "Help", help_path, class: "hover:text-sky-300" %>
<%= link_to current_user.display_name, edit_profile_path, class: "text-white/70 hover:text-sky-300 hidden sm:inline" %>
<%= render "shared/theme_toggle" %>
<%= button_to "Sign out", session_path, method: :delete, class: "rounded bg-white/10 px-2 py-1 hover:bg-white/20" %>