[jira] [Created] (DRILL-7564) Revisit documentation structure

["Paul Rogers (Jira)" <ji...@apache.org>]

Paul Rogers created DRILL-7564:
----------------------------------

             Summary: Revisit documentation structure
                 Key: DRILL-7564
                 URL: https://issues.apache.org/jira/browse/DRILL-7564
             Project: Apache Drill
          Issue Type: Improvement
    Affects Versions: 1.17.0
            Reporter: Paul Rogers


This is a placeholder JIRA to track overall modifications to Drill documentation.

Drill's online documentation is one of the best for an open source project. The original authors documented complex topics starting from nothing other than what developers could provide.

As time has gone on, the earlier efforts have put us in a position where we can now reflect on how people actually use the documentation, and have the luxury of features that are not mature. This gives us an opportunity to review and revise the structure based on experience.

We an also learn from some of the best-structured documentation such as Python and PHP. Drill's documentation will be maintained by volunteers, so we may not be able to follow the patterns of commercial tools such as MySQL.

Presented here is a proposed restructured outline. Creating such an outline takes time, so this ticket will evolve as we discuss and explore our options.

Perhaps documentation can be split into several top-level sections:

* Getting Started: Go from "what's Drill" to running queries on a single-node Drill cluster against local files, example data and easy-to-configure external systems.
* Drill for Users: "How-to" focused discussions of major features for people who want to use Drill to run queries against data sources.
* Drill for Operators: How to deploy Drill in production on bare metal, YARN, K8s and others. How to set up security and so on.
* Reference: SQL, plugin and other reference material.
* Drill for Developers: How to build Drill, how to create plugins and UDFs, etc.

In practice, these might just be groups of chapters with no top-level structure, but it is helpful here to divide up material by target audience.

Crude mapping of existing topics:

* Getting Started
  ** Getting Started / Drill Introduction
  ** Getting Started / Why Drill
  ** Install Drill (local install)
  ** Tutorials (basics)
  ** Configure Drill (local options)
* Drill for Users
 ** Tutorials (beyond the basics)
 ** Connect a Data Source
  ** ODBC/JDBC Interfaces
  ** Query Data
  ** Ecosystem
* Drill for Operators
  ** Drill on Bare Metal
    *** Install Drill (cluster install)
  ** Drill-on-YARN
  ** Drill on K8s (when available)
  ** Configure Drill (cluster settings, security, etc.)
  ** Performance Tuning
  ** Log and Debug
  ** Troubleshooting
* Reference
  ** Release Notes
  ** SQL Reference
  ** Data Sources and File Formats
  ** Sample Datasets
* Drill for Developers
  ** Project Bylaws
  ** Developer Information
  ** Develop Custom Functions



--
This message was sent by Atlassian Jira
(v8.3.4#803005)