streams-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Franklin <m.ben.frank...@gmail.com>
Subject Re: Springcleaning Branch + Discussion
Date Wed, 16 Apr 2014 20:58:25 GMT
On Wed, Apr 16, 2014 at 4:44 PM, Steve Blackmon <sblackmon@apache.org>wrote:

> > 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 don't think anyone likes it; but, as you say it is critical to engagement.


>
> 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.
>

So long as we export the images for the web site one way or another I think
it looks like a good way to start documenting what the various converters
and processors are doing.

It would also be nice if the source files could be stored in our repo.


>
> Steve Blackmon
> sblackmon@apache.org
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message