Build a more organized outline for docs

[verythorough]

The current docs organization was hastily pulled together from what was available in the repo at the time, plus minor updates to content.

To aid discoverability and reduce repetition, I'd like to re-organize the docs files. We can start by discussing here and developing an outline, and then start implementing.

[verythorough]

Here's a first run at an outline. Some sections go deeper than others, but there were some points I wanted to make sure got covered. I'd love to get feedback on organization, anything missing, etc.

I broke it into three main sections to address the different user groups: content editors, people configuring for a site, and people contributing to the project itself. These three sections don't necessarily need to be hosted in the same place, but we can determine those details later.

CMS Docs Outline

Intro

Basic information about the project

• Link to working demo
• Paths/ToC: link to the sections outlined below (Editing, Configuring, Contributing).

Editing Content (issue decaporg/decap-website#2)

Focus on instructions for the content editor end user. Not a place to explain what’s happening “under the hood,” though we may include links here and there for the curious.
(might make this section forkable for hosting a customized version with a configured site)

• Accessing the app: may vary, but describe common use case of website.com/admin
  • troublehooting access?
• UI overview
  • Sidebar
    • editorial workflow - brief description, link to dedicated section
    • collections
      • show existing content
      • create new content
• Content editor
  • Accessed by selecting an existing item or creating a new one
  • Brief explanation of fields and preview
    • required/optional
    • not all field values displayed in preview
    • special widgets like image (link to media library section)
  • Rich text editor
    • Markdown mode
    • Inserting blocks (like image)
  • What “Save” does (depending on whether Editorial Workflow is enabled)
• Media library
  • adding/deleting/searching for assets
  • how to add to content (link to content editor)
• Editorial Workflow
  • getting content into the workflow (by saving changes)
  • moving centent between columns and what that means
  • publishing from the ‘Waiting to go live’ column

Configuration

Focus on instructions and reference material for developers creating a new CMS-enabled site, or integrating the CMS into an existing project.

• Intro ✔️
  • Explanation of basic concepts
  • ToC for sections below
• Start with a Template: quick-deploy templates with built-in CMS ✔️
  • current test-drive.md as example
  • gallery of multiple templates using a variety of generators and backends
• Add to Your Site: step-by-step integration with an existing blog, adapted from quick-start.md. Link to full reference docs where appropriate. ✔️
• Installation & requirements (issue Add a Requirements & Installation doc #731)
  • content
    • must be stored in GitHub repo (for now)
    • supported content file types
  • ‘installing’ the app
    • /admin folder (can be hosted separate from content)
    • index.html: include CMS via <script> tag or npm
    • config.yml: explain purpose & location, link to full reference
• Configuration options (config.yml) (issue Add a Configuration doc #685) ✔️
  • backend: explanation, available options, link to Authentication doc
  • publish_mode: how editorial workflow works with Git, link to content editor UI docs
  • media_folder: what this means, what’s a valid path
  • public_folder: relationship to media_folder, default, valid path info
  • collections: each named collection displays in the sidebar of the app
    • name
    • label: note not pluralized
    • folder or file: briefly explain two types, link to dedicated doc
    • filter: explain, link to doc
    • create: valid with folder type only (?)
    • slug: template options, default (?)
    • fields: will generate key value pairs in data files, or in the frontmatter of markdown files
      • name: note special body value for the main content section of md files
      • label
      • widget: explain, link to dedicated doc
      • default
      • required: defaults to true
      • pattern: basic validation described in validation.md
• Backends & authentication (Issue Add instructions for auth with Netlify Identity and Git Gateway #600) ✔️
  • Detailed config reference and setup guide for available backends:
    • git-gateway
      • requires version 0.5.0+ (currently beta)
      • full instructions for Netlify Identity setup
      • links to repos for DIY GoTrue/Git Gateway setup, plus details on any CMS config differences
    • github
      • full instructions with Netlify OAuth provider setup
      • details and links to other projects for other options (pull from custom-authentication.md)
    • GitLab, Bitbucket when available
• Collection types: file, folder, filter (Issue Add Collection Types doc #679, PR Add collection types doc #883 ) ✔️
  (explain the differences, show config examples for each)
  • file:
    • single file or grouping of files, with fields specified for each file individually
    • can be useful for data files with settings or highly customized pages
    • cannot be filtered; cannot add new items
  • folder:
    • grouping of separate files based on the same template, stored in the same folder
    • UI field will be identical for all items in the folder (or all matching the filter)
    • may or may not be able to add new items (depending on create field)
  • filter:
    • used with folder type
    • can be used to pull only items matching the specified field value
    • requires field and value: must be an exact match
  • Note: regardless of collection type, each item in the main area of the collection browser represents a separate file (though separate files may be combined into a single published page via templating)
• Built-in widgets (Issue Widget docs a bit thin #619, PR Update widget docs #876 ) ✔️
  • Intro to widgets, link to config
  • Reference listing for every type of widget, with the following:
    • UI sample (screenshot, gif, or working demo)
    • required/optional fields, defaults
    • sample config for more complex widgets (like list)
• Custom widgets (Issue Widget docs a bit thin #619, PR Update widget docs #876 ) ✔️
  • Adapt, update, improve extending.md
  • Include advanced validation info from validation.md
• Custom previews (Docs-driven development PR WIP (docs driven development) - Preview API #1311)
  • Adapt, update, improve customization.md

Contribution setup and guidelines

• Code of conduct ✔️
• Adapt, update, improve CONTRIBUTING.md (React Native has a very thorough example.) (Issue Improve contributing guidelines. #1038)
• All contributors recognition & PR instructions for adding/editing contributors ✔️
• Expand on architecture.md?

[verythorough]

Oh, forgot to mention—the top-level bullet points generally represent pages, with the subpoints being sections within the page.

[erquhart]

This should be treated as a story with a set of related issues for the various underlying efforts.

[verythorough]

Agreed! The purpose of this issue was more for discussion about the outline as a whole, before breaking it up into smaller tasks and tying them to related code/design/etc. efforts. It's more about the organization than as a starting point for the actual writing.

[verythorough]

I've broken out the major implementation sections into separate issues. PRs for each of these should include links added to the appropriate section of the Quick Start, because at the moment, it's our main intro. When all of these sections are ready, we can create the Implementation Intro section of the outline, and adapt the Quick Start/Test Drive content to match that outline.

Here's a handy list of the issues to complete for this first round:

• Backends & Authentication (high priority) Add instructions for auth with Netlify Identity and Git Gateway #600
• Widgets Widget docs a bit thin #619 (PR Update widget docs #876 )
• Collections Add Collection Types doc #679 (PR Add collection types doc #883)
• Configuration Add a Configuration doc #685
• Installation Add a Requirements & Installation doc #731

[verythorough]

This is mostly done, with just a few tasks remaining is separate sub-issues:

• Content editor guide Create a user guide for content editors decap-website#2
• Requirements & Installation Add a Requirements & Installation doc #731
• Custom previews WIP (docs driven development) - Preview API #1311 (docs PR for docs-driven Previews API improvements)
• Improve contributor guidelines Improve contributing guidelines. #1038

I'm closing this in favor of those.