[
https://issues.apache.org/jira/browse/AURORA-829?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Stephan Erb updated AURORA-829:
-------------------------------
Description:
As a user of Aurora, I would like the documentation to be more self-contained
and usecase-focused. In its current form, I have to jump back and forth between
_configuration-reference.md_, _user-guide.md_, and _configuration-tutorial.md_
in order to grasp a feature.
*An Example:* Health Checks
* _configuration-reference.md:_
** Describes how to configure health checks.
** Does not tell me what endpoint is monitored
** States that a 'health port' has to be assigned via a 'command line wildcard'
but does not explain what that is supposed to mean.
* _configuration-tutorial.md:_
** Repeats information from the configuration-reference without providing any
additional insights.
* _use-guide.md_:
** Lists the _/health_ endpoint but omits information on what is supposed to be
returned.
** Has only an incomplete example of how to assign a health port (example uses
http port)
As a first step, we could simplify the _configuration-tutorial.md_ by moving
all non-essential property descriptions to the _configuration-reference.md_
(e.g., max_failures, finalization_wait, update_config...)
What do you think?
was:
As a user of Aurora, I would like the documentation to be more self-contained
and usecase-focused. In its current form, I have to jump back and forth between
_configuration-reference.md_, _user-guide.md_, and _configuration-tutorial.md_
in order to grasp a feature.
*An Example:* Health Checks
* _configuration-reference.md:_
** Describes how to configure health checks.
** Does not tell me what endpoint is monitored
** States that a 'health port' has to be assigned via a 'command line wildcard'
but does not explain what that is supposed to mean.
* _configuration-tutorial.md:_
** Repeats information from the configuration-reference without providing any
additional insights.
* _use-guide.md_:
** Lists the _/health_ endpoint but omits information on what is supposed to be
returned.
** Has only an incomplete example of how to assign a health port (example uses
http port)
As a first step, we could simplify the _configuration-tutorial.md_ by moving
all non-essential property descriptions to the _configuration-tutorial.md_
(e.g., max_failures, finalization_wait, update_config...)
> Reference documentation should be self-contained
> ------------------------------------------------
>
> Key: AURORA-829
> URL: https://issues.apache.org/jira/browse/AURORA-829
> Project: Aurora
> Issue Type: Story
> Components: Documentation
> Reporter: Stephan Erb
> Labels: documentaion
>
> As a user of Aurora, I would like the documentation to be more self-contained
> and usecase-focused. In its current form, I have to jump back and forth
> between _configuration-reference.md_, _user-guide.md_, and
> _configuration-tutorial.md_ in order to grasp a feature.
> *An Example:* Health Checks
> * _configuration-reference.md:_
> ** Describes how to configure health checks.
> ** Does not tell me what endpoint is monitored
> ** States that a 'health port' has to be assigned via a 'command line
> wildcard' but does not explain what that is supposed to mean.
> * _configuration-tutorial.md:_
> ** Repeats information from the configuration-reference without providing any
> additional insights.
> * _use-guide.md_:
> ** Lists the _/health_ endpoint but omits information on what is supposed to
> be returned.
> ** Has only an incomplete example of how to assign a health port (example
> uses http port)
> As a first step, we could simplify the _configuration-tutorial.md_ by moving
> all non-essential property descriptions to the _configuration-reference.md_
> (e.g., max_failures, finalization_wait, update_config...)
> What do you think?
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
