accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Keith Turner <ke...@deenlo.com>
Subject Re: [DISCUSS] Reviewing design documents
Date Fri, 04 Apr 2014 18:09:34 GMT
On Fri, Apr 4, 2014 at 1:49 PM, Josh Elser <josh.elser@gmail.com> wrote:

> Granted, the syntax is probably expressive enough to read, but viewing it
> in plaintext isn't the same as having it "rendered".
>
> The lack of varying font size is probably the most noticeable problem.
> Trying to read a table in raw markdown is also a good example. Code
> snippets also are difficult to read.
>

Could post a rendered version of the doc for each version of the source
posted on RB.  Could do this as an attachment on the issue or on
http://people/~committer/


>
> If I'm going to read something high-level, it would be nice to read it
> something other than plaintext. Switching between a plaintext and richtext
> variant of a document is annoying but it isn't the end of the world.
> Plaintext to review, richtext to read.
>
> Perhaps next doc I make I'll just start in markdown/asciidoc instead of
> using something like openoffice/msoffice/googledocs. That would likely
> help.
>
>
> On 4/4/14, 1:40 PM, Keith Turner wrote:
>
>> Why not have the design doc in markdown only?  I assume its not expressive
>> enough?
>>
>> For the ACCUMULO-1000 design doc I used asciidoc to try that out.    The
>> asciidoc source was readable like markdown and maybe more expressive than
>> markdown
>>
>>
>> On Fri, Apr 4, 2014 at 12:45 PM, Josh Elser <josh.elser@gmail.com> wrote:
>>
>>  On 3/28/14, 9:39 AM, Keith Turner wrote:
>>>
>>>  On Fri, Mar 28, 2014 at 12:23 AM, Sean Busbey<busbey+lists@cloudera.com
>>>>
>>>>> wrote:
>>>>>
>>>>
>>>>   >Aside from the occasional stability problem, I really like the idea
>>>> of
>>>>
>>>>> using ReviewBoard. It has the best option for in-context commenting
>>>>>>
>>>>> amongst
>>>>>
>>>>>> our options at Apache AFAICT.
>>>>>>
>>>>>>
>>>>>  Another plus is that the inline discussion threads go w/ a version of
>>>> the
>>>> document.  Josh suggested using 378 as an experiment w/ using RB for
>>>> design
>>>> docs.  I am going to convert it to markdown and post it to RB later
>>>> today.
>>>>
>>>>
>>> I snarked about this on RB, but I'm really not enjoying making the design
>>> doc using markdown so that it can be used in reviewed as plaintext. I
>>> spent
>>> a lot of time with type formatting in a "rich text" editor, to
>>> essentially
>>> have it all thrown away.
>>>
>>> The localized commenting on reviewboard is nice, but making updates to
>>> the
>>> document is definitely not fun.
>>>
>>>
>>

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