[
https://issues.apache.org/jira/browse/HDDS-9613?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782364#comment-17782364
]
Ethan Rose edited comment on HDDS-9613 at 11/3/23 12:52 AM:
------------------------------------------------------------
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.
With global site search, this section may be more useful.
was (Author: erose):
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: [email protected]
For additional commands, e-mail: [email protected]
