search

recoverysource / recoverysource.net

Documentation for Recovery Source projects
https://docs.recoverysource.net/
0 stars 0 forks source link

Refactor Documentation for New Target Audience #1

Open MTecknology opened 5 months ago

MTecknology commented 5 months ago

Current documentation generally expects diligent reading in addition to researching knowledge gaps. Using features like notes, warnings, hover text, etc. would be helpful, but insufficient. The root problem is that documentation is generally the minimum applicable to the project and does not guide users to external documentation (and/or replicate some of it).

Documentation needs to be rewritten with the following considerations:

  1. The target audience should be "grandparents who need help with notepad"; the only exception should be "Developer Corner"
  2. There likely needs to be a "4th-level" (1st non-menu) item underneath each documentation topic that covers a) core concepts (required to understand the following sections) and then, b) via github desktop, and c) via web interface.
  3. Documentation should be task-focused, rather than project-descriptive (except for "Developer Corner") E.g. "Hugo" confuses people and makes them think our documentation is meant to fully cover the hugo project (and also github); it should not appear in top-level menu items, but belongs in "core concepts"
  4. More advanced sections should try to guide inexperienced users away, toward parent/sibling content. E.g. AAMod should guide users toward the Template; Template should guide toward "what is a static website"?
  5. Our documentation should go as far as (but not beyond) walking someone through deploying a custom static website using their own github account, such that they fully understand how DNS works
  6. Cross-references are great, let's use more of them.
  7. A "tutorial" at the end of each section could as a sort of end-of-chapter quiz that helps promote thoroughly reading each section that a person finds themselves viewing.

I'm envisioning the following documentation structure:

This will populate the side menu with the following:

Our Project
  - Recovery Source
  - Getting Started
  - Code of Conduct
  - 7th Tradition
  - Glossary

Fundamentals
  - About Websites
  - About Domains
  - More About DNS
  - About Version Control
  - Working With Github
  - More About Git
  - About Markdown
  - About YAML
  - Common Format Mistakes
  - About Commit Messages

Our Domain Solution
  - About Sober Page
  - Domain Names
  - Email Forwarding

Your First Website
  - Very Basic Site
  - Website with Jekyll
  - Making Changes

Our Website Template
  - About Our Template
  - Start New Site
  - Update Meeting Data
  - Update Basic Pages
  - Update Event Pages
  - Update Menus
  - Update Site Elements
  - Refresh Source Code

Our Template Plugin
  - About Hugo
  - About AAMod
  - AAMod Features
  - Meeting Data Format
  - PDF Generator

Helping Others
  - Github Issues
  - Pull Requests

Developer Corner
  - Core Principals
  - Modify Hugo Themes
  - More About HTML
  - More About CSS
  - Github Actions
MTecknology commented 5 months ago

I used some AI chatbots to help with proof reading and felt pretty good about the responses.

Identify the core audience demographic in the following documentation outline:

The core audience demographic for this documentation outline appears to be individuals involved in addiction recovery programs who are looking to create and manage websites for their organizations. This audience is likely to be familiar with recovery terminology and practices, but may not have extensive technical knowledge or experience with website development. The documentation is tailored to provide guidance on using specific tools and templates to create and update websites for their recovery groups.

Describe the logic flow in the following documentation outline.

The logic flow in this documentation outline starts with an introduction to the project, including information about recovery sources, getting started, code of conduct, 7th tradition, and a glossary of terms. The next section, "Fundamentals," covers basic information about websites, domains, DNS, version control, Git, Markdown, YAML, common format mistakes, and commit messages. Following that, the outline delves into the specific domain solution being offered, including details about Sober Page, domain names, and email forwarding. The next section, "Your First Website," provides guidance on creating a basic website, using Jekyll, and making changes to the site. The outline then introduces "Our Website Template," which includes information about the template, starting a new site, updating meeting data, basic pages, event pages, menus, and site elements. The section on the template plugin, "Our Template Plugin," provides information about Hugo, AAMod, using AAMod, formatting meeting data, and prebuilding. Finally, the "Developer Corner" section covers core principals, modifying Hugo themes, and more information about HTML and CSS. Overall, the logic flow of the outline progresses from general project information to fundamental concepts, specific solutions, website creation, template usage, template plugins, and developer tools.

Assuming this documentation has complete pages explaining each page title, and given a target audience that [...], identify exact gaps in this documentation that may need supplemental sections.

This reliably came up with general web advice that is primarily applicable to dynamic sites and/or out of scope; examples: SEO, Security, Performance Optimization, Working with APIs