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