Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build a more organized outline for docs #598

Closed
verythorough opened this Issue Sep 13, 2017 · 6 comments

Comments

Projects
2 participants
@verythorough
Copy link
Contributor

verythorough commented Sep 13, 2017

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

This comment has been minimized.

Copy link
Contributor Author

verythorough commented Sep 27, 2017

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 #1340)

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 #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 #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 #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 #679, PR #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 #619, PR #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 #619, PR #876 ) ✔️
    • Adapt, update, improve extending.md
    • Include advanced validation info from validation.md
  • Custom previews (Docs-driven development PR #1311)
    • Adapt, update, improve customization.md

Contribution setup and guidelines

@verythorough

This comment has been minimized.

Copy link
Contributor Author

verythorough commented Sep 27, 2017

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

@verythorough verythorough moved this from Ready for Assignment to Ready for Review in Sprint Planning | Sprint 6 (11/23 - 12/6) Sep 27, 2017

@erquhart erquhart moved this from Ready for Review to In Progress in Sprint Planning | Sprint 6 (11/23 - 12/6) Oct 2, 2017

@erquhart

This comment has been minimized.

Copy link
Member

erquhart commented Oct 2, 2017

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

@verythorough

This comment has been minimized.

Copy link
Contributor Author

verythorough commented Oct 5, 2017

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

This comment has been minimized.

Copy link
Contributor Author

verythorough commented Oct 25, 2017

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:

@verythorough

This comment has been minimized.

Copy link
Contributor Author

verythorough commented May 6, 2018

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

  • Content editor guide #1340
  • Requirements & Installation #731
  • Custom previews #1311 (docs PR for docs-driven Previews API improvements)
  • Improve contributor guidelines #1038

I'm closing this in favor of those.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.