I would really like to review the design doc posted on ACCUMULO-378, but I would rather not do that on Google docs. I would like to use Apache infrastructure and have the discussion around the design doc archived in the mailing list.
One option is to use Markdown + RB and never check the design documents in anywhere. Basically we generate a patch that posed to RB, but never checked in. Or maybe we could check the design docs in somewhere.
I've seen other projects upload a file to the appropriate JIRA and that seemed to work well. I don't have specific experience with that, though, so I cannot warn you about any pitfalls. On Thu, Mar 27, 2014 at 6:05 PM, Keith Turner <[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.
I think the finished doc (preferably in markdown) could just be attached to the jira that's relevant. I'd like to see a pipeline for incorporating information from the design doc into our user facing documentation or javadocs, but I wouldn't want to just push them over as-is since the audience is different.
-Sean On Thu, Mar 27, 2014 at 7:37 PM, Josh Elser <[EMAIL PROTECTED]> wrote:
Could this be a good test case for Gerrit? On Fri, Mar 28, 2014 at 12:23 AM, Sean Busbey <busbey+[EMAIL PROTECTED]>wrote: // Bill Havanki // Solutions Architect, Cloudera Govt Solutions // 443.686.9283
On Fri, Mar 28, 2014 at 12:23 AM, Sean Busbey <busbey+[EMAIL PROTECTED]>wrote: 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.
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:
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 Fri, Apr 4, 2014 at 1:49 PM, Josh Elser <[EMAIL PROTECTED]> wrote: 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/