[
https://issues.apache.org/jira/browse/DRILL-7564?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17028617#comment-17028617
]
Charles Givre commented on DRILL-7564:
--------------------------------------
I really like the proposed structure. Is there a way we can create a "dev
site" so that we can start working on this in small bits?
> 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
> Priority: Major
>
> 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)
