accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Josh Elser <>
Subject Re: [DISCUSS] Reviewing design documents
Date Fri, 04 Apr 2014 17:49:36 GMT
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.

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 <> wrote:
>> On 3/28/14, 9:39 AM, Keith Turner wrote:
>>> On Fri, Mar 28, 2014 at 12:23 AM, Sean Busbey<
>>>> 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.

View raw message