You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@ozone.apache.org by "Ethan Rose (Jira)" <ji...@apache.org> on 2023/11/03 00:52:00 UTC
[jira] [Commented] (HDDS-9613) [Website v2] Documentation
[ https://issues.apache.org/jira/browse/HDDS-9613?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782364#comment-17782364 ]
Ethan Rose commented on HDDS-9613:
----------------------------------
We should discuss the high level layout of the documentation on the new website before creating individual pages. This will help keep content focused and organized. I will start by proposing the following sections:
h2. Getting Started
This section would contain a high level overview of the Ozone components, minimal installation steps on various platforms (bare metal vs docker test setup), configuration basics, and the minimal CLI knowledge required to read and write objects.
h2. User Guide
This section would be for end users working against an already setup Ozone cluster. It would contain sections like CLIs, Java client API, bucket layouts, integration with other systems like Spark and Impala, authenticating with Kerberos and with S3 secrets, etc.
h2. Administrator Guide
This section would contain extra content that administrators would need to know, but end users probably won't need to worry about. Things like disk replacement, decommissioning, troubleshooting, metrics and dashboarding, performance tuning, security etc. This would probably be the largest section of the docs.
h2. Developer Guide
This section would contain most of the content that currently resides on the Ozone wiki or various README.md files throughout the Ozone repo. Things like the release guide, setting up Intellij, running tests locally, Github Actions usage, etc.
h2. System Design
This section would contain explanations of Ozone internals. Everything from high level concepts like containers and pipelines to feature specific implementation like FSO RocksDB layout. It would be a more cohesive version of our current practice of linking outdated design docs at https://ozone.apache.org/docs/current/design.html.
h2. Glossary
This section may be nice to have, but I am curious what others think. Here we could:
- Define Ozone specific terms like "container", "Ratis", "FSO".
- Clarify Ozone related terms with overloaded definitions, like "snapshot" (Ratis snapshot, RocksDB snapshot, filesystem snapshot) and "volume" (datanode volume, OM volume).
- Provide quick definitions for Ozone adjacent terms like "Raft", "RocksDB", "SPNEGO". Just enough detail to unblock someone who sees them come up in a sentence elsewhere in the docs.
> [Website v2] Documentation
> --------------------------
>
> Key: HDDS-9613
> URL: https://issues.apache.org/jira/browse/HDDS-9613
> Project: Apache Ozone
> Issue Type: Improvement
> Components: documentation, website
> Reporter: Ethan Rose
> Assignee: Ethan Rose
> Priority: Major
>
> Parent Jira to track documentation related tasks for the new and improved Ozone website.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org