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)
