drill-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Paul Rogers (Jira)" <j...@apache.org>
Subject [jira] [Created] (DRILL-7564) Revisit documentation structure
Date Sun, 02 Feb 2020 22:29:00 GMT
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

View raw message