Distributed Documentation?

8 Messages Forum Options Options
Embed this topic
Permalink
A Bowtell
Distributed Documentation?
Reply Threaded MoreMore options
Print post
Permalink
I'm just going to come out of the corner where I'm working on some
documentation and throw a suggestion in the air. I work in an
environment where things are very distributed and where people are free
to do their own thing and do so for very good reasons. I've learnt that
you have to go with the flow.

When I was starting with Plone I found some great documentation out
there and it wasn't all on plone.org (though that was good too). When I
was a teacher I found that my students had a variety of different
learning styles, needed to look at things from many different angles and
that there was no definitive way through a subject. Often too, when
tackling a subject you need to be inventive and to try different
approaches and formats. plone.org might not be the best place to try all
of this out or deliver all of this.

Is there a chance we could embrace the idea of distributed
documentation? My thought is that perhaps by suggesting a set of
metadata to describe a piece of documentation out there on the web (not
just on plone.org), we could encourage authors to drop a snippet of RDF
into their work, which, at some future date, we could harvest (a bit
like DOAP) and possibly annotate further.

Now I'm going to go back into my corner and take cover, while I just get
on with the documentation I've promised and hope to deliver in a couple
of weeks.

Anne



-------------------------------------------------------------------------
This SF.net email is sponsored by the 2008 JavaOne(SM) Conference
Don't miss this year's exciting event. There's still time to save $100.
Use priority code J8TL2D2.
http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs
Graham Perrin
Re: Distributed Documentation?
Reply Threaded MoreMore options
Print post
Permalink
A Bowtell wrote:
Is there a chance we could embrace the idea of distributed documentation? My thought is that perhaps by suggesting a set of metadata to describe a piece of documentation out there on the web (not just on plone.org), we could encourage authors to drop a snippet of RDF into their work, which, at some future date, we could harvest (a bit like DOAP) and possibly annotate further.
I'm not familiar with the RDF/DOAP routine but I *definitely* like the idea of distributed documentation and diverse styles.

Personally, something like 30% to 50% of what I find most useful exists beyond the plone.org domain...
vedaw
Re: Distributed Documentation?
Reply Threaded MoreMore options
Print post
Permalink
In reply to this post by A Bowtell
Hi Anne,

I think you're 100% right in saying that we somehow need to capture third party distributed documentation. At this point, we're not technologically ready to slice and dice distributed docs, but as a first step, I think that we can start with a page that aggregates all of the external documentation people have been writing and offer it up as a resource. People can submit a ticket and ask to be included on the list, and we just add their URLs and do occasional gardening.

Thanks for pointing out that we need to capture docs of this nature, even if we're not sure what we'll do with them in the future.

Cheers,

- Veda

A Bowtell wrote:
Is there a chance we could embrace the idea of distributed
documentation? My thought is that perhaps by suggesting a set of
metadata to describe a piece of documentation out there on the web (not
just on plone.org), we could encourage authors to drop a snippet of RDF
into their work, which, at some future date, we could harvest (a bit
like DOAP) and possibly annotate further.

Now I'm going to go back into my corner and take cover, while I just get
on with the documentation I've promised and hope to deliver in a couple
of weeks.

Anne



-------------------------------------------------------------------------
This SF.net email is sponsored by the 2008 JavaOne(SM) Conference
Don't miss this year's exciting event. There's still time to save $100.
Use priority code J8TL2D2.
http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone
_______________________________________________
Plone-docs mailing list
Plone-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/plone-docs
Graham Perrin
Re: Distributed Documentation?
Reply Threaded MoreMore options
Print post
Permalink
vedaw wrote:
as a first step, I think that we can start with a page that aggregates all of the external documentation people have been writing and offer it up as a resource. People can submit a ticket and ask to be included on the list, and we just add their URLs and do occasional gardening.
Feel free to use <http://groups.diigo.com/groups/ploned>.

I already have a _personal_ collection of Plone-related bookmarks <http://www.diigo.com/user/grahamperrin/plone>, some of which I'll move to the _group_ collection.

(Also available: a more 'valuable' URL <http://groups.diigo.com/groups/plone> but I don't intend to take that one.)

Kind regards
Graham
vedaw
Re: Distributed Documentation?
Reply Threaded MoreMore options
Print post
Permalink
Thanks for pointing me to this. Ideally, we'll pull from these lists and put
it on a page on plone.org itself. That way we're not reliant on a 3rd party
product and extra tools.

I'll add it to the project site as well.

- Veda


On 4/10/08 11:06 PM, "grahamperrin" <G.J.Perrin@...> wrote:

>
>
> vedaw wrote:
>> as a first step, I think that we can start with a page that aggregates all
>> of the external documentation people have been writing and offer it up as
>> a resource. People can submit a ticket and ask to be included on the list,
>> and we just add their URLs and do occasional gardening.
>
> Feel free to use <http://groups.diigo.com/groups/ploned>.
>
> I already have a _personal_ collection of Plone-related bookmarks
> <http://www.diigo.com/user/grahamperrin/plone>, some of which I'll move to
> the _group_ collection.
>
> (Also available: a more 'valuable' URL
> <http://groups.diigo.com/groups/plone> but I don't intend to take that one.)
>
> Kind regards
> Graham


-------------------------------------------------------------------------
This SF.net email is sponsored by the 2008 JavaOne(SM) Conference
Don't miss this year's exciting event. There's still time to save $100.
Use priority code J8TL2D2.
http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs
Graham Perrin
Distributed documentation: sharing, bookmarking, highlighting, commenting, sticky notes and discussion
Reply Threaded MoreMore options
Print post
Permalink
Reviewing this April discussion alongside more recent
<http://n2.nabble.com/Plone.org-documentation-process-considered-harmful-tp1483044p1485470.html> ... 

vedaw wrote:
Graham Perrin wrote:
Feel free to use <http://groups.diigo.com/groups/ploned>.

I already have a _personal_ collection of Plone-related bookmarks <http://www.diigo.com/user/grahamperrin/plone>, some of which I'll move to the _group_ collection.
Thanks for pointing me to this. Ideally, we'll pull from these lists and put it on a page on plone.org itself. That way we're not reliant on a 3rd party product and extra tools.

I'll add it to the project site as well.
There's also
<http://groups.diigo.com/groups/ploneadm>.

The following examples demonstrate that highlights, sticky notes and comments are easily shared with the public (or with groups), if you so choose:

<http://www.diigo.com/annotated/21b2d4feaf0a4a269e81d81dcab3759b>
<http://www.diigo.com/annotated/8416ae818f9039137009f05e5e09c0cf>
<http://www.diigo.com/annotated/573bd2866683ab0136353688530ed63f>

-- to view such annotations, there's no requirement to be a member/user of Diigo.

For those who do wish to use Diigo: it's OpenID-enabled -- Google OpenID included. Aspects such as this have the potential to significantly lower any barriers that are perceived by people who wish to contribute to (or at least comment upon) documentation relating to Plone.

Export to XML and other formats are available.

Regards
Graham
JoAnna Springsteen
Re: Distributed documentation: sharing, bookmarking, highlighting, commenting, sticky notes and discussion
Reply Threaded MoreMore options
Print post
Permalink
> There's also
> <http://groups.diigo.com/groups/ploneadm>.
>
> The following examples demonstrate that highlights, sticky notes and
> comments are easily shared with the public (or with groups), if you so
> choose:
>
> <http://www.diigo.com/annotated/21b2d4feaf0a4a269e81d81dcab3759b>
> <http://www.diigo.com/annotated/8416ae818f9039137009f05e5e09c0cf>
> <http://www.diigo.com/annotated/573bd2866683ab0136353688530ed63f>
>
> -- to view such annotations, there's no requirement to be a member/user of
> Diigo.


Interesting. We played with annotations a year or two back but they
weren't as cool as this.
/me likes this way better than adding a comment.

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs
Graham Perrin
Re: Distributed documentation: sharing, bookmarking, highlighting, commenting, sticky notes and discussion
Reply Threaded MoreMore options
Print post
Permalink
JoAnna Springsteen wrote:
Interesting. We played with annotations a year or two back but they
weren't as cool as this.
/me likes this way better than adding a comment.
Hop on board. Diigo developers and community are very interested in, and remarkably responsive to, suggestions from users.