Return-Path: X-Original-To: apmail-streams-dev-archive@minotaur.apache.org Delivered-To: apmail-streams-dev-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 42F3F10570 for ; Wed, 16 Apr 2014 20:45:24 +0000 (UTC) Received: (qmail 37989 invoked by uid 500); 16 Apr 2014 20:45:23 -0000 Delivered-To: apmail-streams-dev-archive@streams.apache.org Received: (qmail 37934 invoked by uid 500); 16 Apr 2014 20:45:23 -0000 Mailing-List: contact dev-help@streams.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@streams.incubator.apache.org Delivered-To: mailing list dev@streams.incubator.apache.org Received: (qmail 37925 invoked by uid 99); 16 Apr 2014 20:45:23 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 16 Apr 2014 20:45:22 +0000 X-ASF-Spam-Status: No, hits=0.0 required=5.0 tests=HELO_NO_DOMAIN X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Wed, 16 Apr 2014 20:45:18 +0000 Received: (qmail 37038 invoked by uid 99); 16 Apr 2014 20:44:52 -0000 Received: from minotaur.apache.org (HELO minotaur.apache.org) (140.211.11.9) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 16 Apr 2014 20:44:52 +0000 Received: from localhost (HELO mail-vc0-f169.google.com) (127.0.0.1) (smtp-auth username sblackmon, mechanism plain) by minotaur.apache.org (qpsmtpd/0.29) with ESMTP; Wed, 16 Apr 2014 20:44:52 +0000 Received: by mail-vc0-f169.google.com with SMTP id ik5so11883992vcb.28 for ; Wed, 16 Apr 2014 13:44:51 -0700 (PDT) X-Gm-Message-State: ALoCoQlVh4bLwntE2gQJIHdWNbpIeGEJeV4Clu+c7kNAYcY6jf8R6Mr2MagX9jx/LBbYcqrafJR5 MIME-Version: 1.0 X-Received: by 10.220.188.10 with SMTP id cy10mr114411vcb.36.1397681091624; Wed, 16 Apr 2014 13:44:51 -0700 (PDT) Received: by 10.220.169.194 with HTTP; Wed, 16 Apr 2014 13:44:51 -0700 (PDT) X-Originating-IP: [204.57.79.12] In-Reply-To: References: Date: Wed, 16 Apr 2014 15:44:51 -0500 Message-ID: Subject: Re: Springcleaning Branch + Discussion From: Steve Blackmon To: dev@streams.incubator.apache.org Content-Type: text/plain; charset=UTF-8 X-Virus-Checked: Checked by ClamAV on apache.org > I think we need another to document the architecture of these components > and where to get started on the website. Right now, the only diagram we > have is the Camel one. > So let me say first that I hate writing documentation. So much so that it if it doesn't practically write itself I usually don't bother. But I agree it's essential to encourage adoption and to help us hash out how we want to actually use the activity streams spec, out of all the ways it might be used. I've been playing around looking for a light-weight interface that could simultaneously help me document the assumptions and output of individual streams serializers and processors, and serve as a planning tool for modules that are still on the drawing board, and I think I've found something that might work. To get a sense for what that might look like, browse to this repo and click into both submodules: https://github.com/w2ogroup/streams-documentation Basically README.md file (or some external site) embeds a png of a mindmap generated from a MUP file, which anyone can create or edit using http://www.mindmup.com/. The MUP files themselves reside under source control as well. MindMup is multi-user, powerful, easy to use, with good keyboard shortcuts and source code available under a liberal license. The diagrams on that site took about 10 minutes to create. I can't imagine producing pictures nearly so robust in text-only, or spending less than an hour trying. Please let me know if you think this is a good idea, a terrible idea, or something in between. Steve Blackmon sblackmon@apache.org