A high-level working draft of Solidus's documentation structure

proposed-solidus-docs-table-of-contents.md

Proposed table of contents for Solidus documentation

This document is a high-level working draft. Where and how this documentation will exist is still up for discussion.

Note that list items that are crossed out mean that essential documentation for that topic has been merged.

Admin

TBD. This documentation will likely re-present content from the developer documentation in a simplified way. This would be specifically concerning the admin panel UI, ecommerce concepts that are integral to Solidus, and doing business day-by-day with it.

Developers

It goes without saying: this whole guide should be clearly marked as a guide for developers.

Getting started

Guides appropriate for developers who haven't used Solidus before. This section acts as an introduction and bridge into the other sections.

• Introduction to Solidus
  • How is Solidus different from Spree?
• First-time installation
• Developing Solidus
• Installation options
• Before you start development
  • Spree and Solidus data models
  • Overview of Solidus gems
  • Common development patterns and best practices
  • Links to other useful Solidus documentation for new Solidus developers
• Contributing to Solidus

Basic

Details core Solidus functionality, concepts, and extending their functionality. This section would cover the store elements that most developers would need to change in some way for a store.

For example, "As a developer, I need to change the customer signup form so that it includes custom fields."

• Cart
• Checkout
  • Standard checkout behavior
    • Optional registration step
      • Address information
      • Delivery options
      • Payment step
      • Order confirmation
  • Customizing the checkout flow
    • Checkout domain-specific language (DSL)
    • Add or remove steps from the checkout flow
    • Checkout breadcrumbs
  • Payment profiles
  • Coupon codes
• Users (Accounts)
  • Addresses
  • Authentication
    • solidus_auth_devise
    • Custom authentication setup
  • The user model
  • Add custom fields for user accounts
  • Logged in customer areas
  • Guest accounts
• Inventory
  • Stock management from the admin panel
    • Return authorizations
  • Inventory tracking
• Locations
  • Overview
  • Countries and states
  • Zones
• Mail
  • Mailers
• Orders
  • Overview of the order flow
  • The address model
  • The order model
  • Order adjustments
  • Order states
  • Line items
  • Order updates
  • Cancellations
• Payments
  • Payment states
  • Payment methods
    • Bogus payment methods
  • Payment processing
  • Store credit (Wallet)
  • Auto-capturing payments
  • Logs
  • Custom gateways
• Products and variants
  • Overview
  • Multi-currency support
    • Variants
    • Master variants
    • Option types and values
    • Product properties
    • Product images
    • Paperclip
    • Taxonomies and taxons
• Promotions
  • Overview
  • Promotion handlers
  • Promotion actions
  • Promotion rules
  • Create custom promotion actions
  • Create custom promotion rules
• Shipments
  • Overview
  • Cartons (stub)
    • Custom shipping calculators
  • Shipment setup examples
    • Simple example
    • Complex example
    • Shipping method filters
    • solidus_active_shipping extension
  • Split shipments
    • Shipments user interface
• Taxation
  • Overview
  • Custom tax calculators
    • Displaying prices
    • Default tax calculator
    • Dealing with multiple tax jurisdictions
  • Example tax setups
    • Simple sales tax example
    • Simple VAT example
    • Complex sales tax example
    • Complex VAT example
    • Value-added tax (VAT)

Advanced

Details store functionality that would not require changes for typical stores. This functionality would likely be changed only in the context of larger projects where Solidus's built-in functionality would need to be extended or changed more dramatically.

For example, "As a developer, I need to create a custom frontend for Solidus." Or, "As a developer, I need to create custom calculators for a subscription product, where shipping charges change overtime as customers remain loyal."

These topics would be inherently more customization-heavy.

• Assets
  • solidus_frontend
  • solidus_backend
    • Overriding Solidus assets
    • Asset management (Rails assets pipeline)
• Calculators
  • Overview of typical calculators
  • Create a custom calculator
  • Calculated adjustments
• Configuration and Preferences
  • Main configuration object (Spree initializer)
  • Model preferences
    • Defining preferences
    • Accessing preferences
  • Site-wide preferences
• Databases
• Extensions
  • Installing extensions
  • Extension development
  • Common problems and troubleshooting
• Internationalization (i18n)
  • Localization
  • Multi-language stores
  • Multi-country stores
• Permissions (Roles, Access Controls)
• Testing
  • Solidus test suite
  • Extension testing
  • Writing Solidus tests
• Views, models, and controllers
  • Class extension points
  • Decorators
  • Override controller action responses

System administration

This section discusses hygiene and configuration for deploying and administrating a server that runs Solidus.

• Deployment
  • Cloud deployments
    • AWS
    • Heroku
    • Recommended deployment configurations
    • SSL
• Content delivery networks (CDNs)
• Image storage with Amazon S3
• Migration
• Security
• Upgrades
  • Safe upgrade checklist
  • Common upgrade problems