You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@reef.apache.org by Markus Weimer <ma...@weimo.de> on 2016/06/09 17:59:56 UTC
Where to write designs?
Hi,
designs evolve over time, which relies on feedback and discussion. An
example is REEF-1223, which is the design / discussion for the first
level of fault tolerance in IMRU. There is a design document attached,
but also a very large discussion thread.
For someone new to the subject, it is pretty hard to ramp up on our
current thinking on the matter. Similarly, leaving comments is getting
harder with time, as the design doc is read-only and probably not current.
I believe we need better tools for this. In my day job, we use shared
documents and inline comments for this. That way, we have a "living
document" which is always current and contains *anchored* comments by
everybody. When this converges, we have a design.
Maybe we could use the wiki for this? At least, it would create a living
document with a URL. However, CWiki doesn't seem to support anchored
comments. Another option would be to use one of the cloud word
processors and link to those docs?
WDYT? Is this a concern that needs addressing?
Markus
Re: Where to write designs?
Posted by Markus Weimer <ma...@weimo.de>.
On 2016-06-09 11:28 AM, Ashvin A wrote:
> As a new user of REEF, I often find myself lost in jira comments,
> documents with stale information and mail threads.
Do you know of open development processes which don't suffer from this?
I can see a very laborious way to not have the problem: Continuously
curate JIRAs and keep the description up to date. I have done that in
the past, but can't keep up with the current flood of comments, emails
and changes.
In your particular case, you also suffer extra-bad with REEF, as we
haven't setup a user list yet. Following all the JIRAs and other
comments must be overwhelming. Maybe we should setup
user@reef.apache.org after all :)
> A living-versioned document will be very useful. I have one small
> concern though. It is possible to delete comments and some important
> detail might get lost.
That is not a small concern. If we loose important parts of the
discussion because of it, we loose one of the main benefits of open
software development. Right now, every code change is incredibly well
documented here, in JIRA and on GitHub. That facilitates debugging as
well as "lurking": Everybody knows what will change in REEF and can
chime in. Once we hide this just one click away in a doc, that will
become harder. Even worse would be to loose comments, which are
important contributions.
Markus
Re: Where to write designs?
Posted by Ashvin A <aa...@gmail.com>.
+1
Thanks for starting this discussion. As a new user of REEF, I often find
myself lost in jira comments, documents with stale information and mail
threads. A living-versioned document will be very useful. I have one small
concern though. It is possible to delete comments and some important detail
might get lost.
On Thu, Jun 9, 2016 at 10:59 AM, Markus Weimer <ma...@weimo.de> wrote:
> Hi,
>
> designs evolve over time, which relies on feedback and discussion. An
> example is REEF-1223, which is the design / discussion for the first level
> of fault tolerance in IMRU. There is a design document attached, but also a
> very large discussion thread.
>
> For someone new to the subject, it is pretty hard to ramp up on our
> current thinking on the matter. Similarly, leaving comments is getting
> harder with time, as the design doc is read-only and probably not current.
>
> I believe we need better tools for this. In my day job, we use shared
> documents and inline comments for this. That way, we have a "living
> document" which is always current and contains *anchored* comments by
> everybody. When this converges, we have a design.
>
> Maybe we could use the wiki for this? At least, it would create a living
> document with a URL. However, CWiki doesn't seem to support anchored
> comments. Another option would be to use one of the cloud word processors
> and link to those docs?
>
> WDYT? Is this a concern that needs addressing?
>
> Markus
>