aurora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tom Galloway" <tgallo...@twitter.com>
Subject Re: Review Request 16615: Client command hooks doc
Date Wed, 08 Jan 2014 01:17:54 GMT


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/README.md, line 17
> > <https://reviews.apache.org/r/16615/diff/1/?file=414585#file414585line17>
> >
> >     Please remove trailing whitespace throughout all files.  Ultimately, the RB
diff should show no red columns.

I'm a bit confused here. In Markdown, not having 2 spaces at the end of lines in lists or
code or the like causes the next line to run into its above line. I'm not going to be able
to eliminate that without messing up the displayed formatting significantly.


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/clientcommands.md, line 7
> > <https://reviews.apache.org/r/16615/diff/1/?file=414586#file414586line7>
> >
> >     Is the "aurora help open" bit necessary?  Rather than "due to...", might be
better to cite a JIRA issue tracking the fix.

I think it's necessary for users to understand why the help command doesn't work for this
one subcommand. Personally, as a reader, I'd prefer the brief explanation to a "because we
said so" uninformative response. Remember, these are the open source docs, so readers won't
have access to JIRA tickets.


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/clientcommands.md, line 14
> > <https://reviews.apache.org/r/16615/diff/1/?file=414586#file414586line14>
> >
> >     i'm mostly markdown-ignorant, but can you let markdown do the list indentation
for you?
> >     
> >     http://daringfireball.net/projects/markdown/syntax#list

I don't claim to be an expert myself, but I just know I had intermittent problems when I tried
letting it handle the indentation, so I did it myself to be sure.


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/clientcommands.md, line 33
> > <https://reviews.apache.org/r/16615/diff/1/?file=414586#file414586line33>
> >
> >     Is there a reason the raw anchor tag is here rather than using what appears
to be built-in support for them?
> >     
> >     http://stackoverflow.com/questions/5319754/cross-reference-named-anchor-in-markdown/7335259#7335259

I think you misread the answer to the question asked in Stack Overflow. Markdown has built-in
support for referring to a named anchor of the form [text](#anchor-name), but the named anchor
can only be set via <a name="anchor-name"></a>. Yeah, I think it's mixed up that
they didn't bother to implement a version of <a> in a Markdown like syntax despite doing
so with how you use the named anchors.


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/clientcommands.md, line 38
> > <https://reviews.apache.org/r/16615/diff/1/?file=414586#file414586line38>
> >
> >     (nitpick) Client seems to be deliberately capitalized when preceded by Aurora.
 is there a convention being followed?  i figured 'Aurora' is the proper noun and the qualifier/component
would not be considered proper.

It's something I got into the habit of when working on the Hooks document and needed to distinguish
between the command line client and API. I'm considering the "Aurora Client" to be a separate
thing from "Aurora" and deserving of capitalization. I'd probably use "Aurora's client..."
if I'd ever referred to it that way.


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/clientcommands.md, lines 70-74
> > <https://reviews.apache.org/r/16615/diff/1/?file=414586#file414586line70>
> >
> >     Consider east/west rather than cluster1/cluster2.

Any particular reason? "cluster1" and "cluster2" make it clear that's the cluster part of
the job key, and while east/west applies to us (and I guess a number of other companies),
I don't really see any reason to use them in the docs.


> On Jan. 6, 2014, 10:51 p.m., Bill Farner wrote:
> > docs/clientcommands.md, line 43
> > <https://reviews.apache.org/r/16615/diff/1/?file=414586#file414586line43>
> >
> >     Can intra-doc links help reduce the prose?  If the text 'Job keys' linked to
the appropriate anchor, the reader will probably be just as compelled to check it out.
> >     
> >     In fact, i suggest that all section references be formally linked rather than
just capitalized.

Probably worth considering for a subsequent update, but I don't think the benefits of such
links overcome the time it'd take to go through the docs finding the appropriate locations
vis a vis getting these docs out to the public.


- Tom


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/16615/#review31278
-----------------------------------------------------------


On Jan. 3, 2014, 7:19 p.m., Tom Galloway wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/16615/
> -----------------------------------------------------------
> 
> (Updated Jan. 3, 2014, 7:19 p.m.)
> 
> 
> Review request for Aurora.
> 
> 
> Repository: aurora
> 
> 
> Description
> -------
> 
> Client command hooks doc
> 
> 
> Resource isolation doc
> 
> 
> Configuration tutorial
> 
> 
> User guide doc
> 
> 
> Configuration file reference
> 
> 
> Tutorial doc
> 
> 
> Client commands doc
> 
> 
> User doc overview
> 
> 
> Doc images
> 
> 
> Adding initial image in images directory
> 
> 
> Diffs
> -----
> 
>   docs/README.md PRE-CREATION 
>   docs/clientcommands.md PRE-CREATION 
>   docs/configurationreference.md PRE-CREATION 
>   docs/configurationtutorial.md PRE-CREATION 
>   docs/hooks.md PRE-CREATION 
>   docs/images/CPUavailability.png PRE-CREATION 
>   docs/images/HelloWorldJob.png PRE-CREATION 
>   docs/images/RoleJobs.png PRE-CREATION 
>   docs/images/ScheduledJobs.png PRE-CREATION 
>   docs/images/TaskBreakdown.png PRE-CREATION 
>   docs/images/aurora_hierarchy.png PRE-CREATION 
>   docs/images/killedtask.png PRE-CREATION 
>   docs/images/lifeofatask.png PRE-CREATION 
>   docs/images/runningtask.png PRE-CREATION 
>   docs/images/stderr.png PRE-CREATION 
>   docs/images/stdout.png PRE-CREATION 
>   docs/resourceisolation.md PRE-CREATION 
>   docs/tutorial.md PRE-CREATION 
>   docs/userguide.md PRE-CREATION 
> 
> Diff: https://reviews.apache.org/r/16615/diff/
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Tom Galloway
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message