falcon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ajay Yadava (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (FALCON-1587) Divide FalconCLI.twiki into sub sections for different modules on the lines of REST Api
Date Wed, 18 Nov 2015 13:20:11 GMT

    [ https://issues.apache.org/jira/browse/FALCON-1587?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15010959#comment-15010959
] 

Ajay Yadava commented on FALCON-1587:
-------------------------------------

[~shwethags] I will try to alleviate all your concerns one by one in separate comments (please
bear with me for lengthy comments)

{quote}
In general, users tend to use multiple commands in sequence - for example, rerun an instance
and get its status. If all commands are in one page, you can get the info much faster than
navigating across 3 pages in this case(main page with links and 2 pages for commands).
{quote}

Interestingly, this is not generally how users are using current documentation. The assumption
that they get all information in one page and don't have to make any more clicks is not true.
Most users are even now doing multiple clicks. They open the general CLI documentation for
a command (which is very _terse_ , doesn't contain any example or explanation) and then they
click the link at the end which generally reads something like "Optional params described
here". For example please find below the documentation for entity list. There is no way a
user can just look at it and understand all the options.


{code}
---+++List

Entities of a particular type can be listed with list sub-command.

Usage:
$FALCON_HOME/bin/falcon entity -list

Optional Args : -fields <<field1,field2>>
-type <<[cluster|datasource|feed|process],[cluster|datasource|feed|process]>>
-nameseq <<namesubsequence>> -tagkeys <<tagkeyword1,tagkeyword2>>
-filterBy <<field1:value1,field2:value2>> -tags <<tagkey=tagvalue,tagkey=tagvalue>>
-orderBy <<field>> -sortOrder <<sortOrder>> -offset 0 -numResults
10

<a href="./Restapi/EntityList.html">Optional params described here.</a>
{code}

> Divide FalconCLI.twiki into sub sections for different modules on the lines of REST Api
> ---------------------------------------------------------------------------------------
>
>                 Key: FALCON-1587
>                 URL: https://issues.apache.org/jira/browse/FALCON-1587
>             Project: Falcon
>          Issue Type: Improvement
>          Components: docs
>            Reporter: Ajay Yadava
>            Assignee: Praveen Adlakha
>              Labels: docs, newbie
>         Attachments: FALCON-1587-v1.patch, FALCON-1587-v2.patch, falcon_1587.patch
>
>
> Currently FalconCLI.twiki is one monolithic file. We should create another file for each
command and link it back in FalconCLI.twiki, just like REST Api.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Mime
View raw message