Re: Re: Documentation effort

classic Classic list List threaded Threaded
6 messages Options
Martin Aspeli-2 Martin Aspeli-2
Reply | Threaded
Open this post in threaded view
|

Re: Re: Documentation effort


> The reason I'm asking here is that there's no point in us doing it, if
> similar efforts are planned/underway.  It doesn't sound like you
> documentation folks are doing anything like it, so it's safe for us to
> spend some time working on documentation and a site..

Like limi says... running code wins. demo.plone.org was a good idea that  
got neglected. If you can provide the bandwidth (both in man-hours and  
hosting) to get a decent demo going and demonstrate to end users how to  
use Plone effectively, this would indeed be a very good thing for Plone,  
and we would welcome it.

> Yeah - more of a step-by-step tutorial than a reference.  We're just
> guiding users through the first steps of using Plone.

We're lacking this, definitely. JoAnna said she wanted to help too, so try  
to co-ordinate with her. But there is a definite market for such  
documentation.

> I'm thinking we should cover setting user preferences, adding of some
> content types, and then maybe cover how to manage this content reviewers.

+1

>> As I've found - and maybe other people have as well - there's a bit of  
>> "great
>> site, now what?" for newbies on a Plone installation.
>
> Yep.

We know all too well. :)

We'd be very grateful for this if you can offer the time to produce it and  
keep it up to date. It would be best, however, if you can put the  
documentation up as a reference manual on plone.org/documentation/manual,  
that'd be best - the more scattered documentation is, the less effective  
it is, and on plone.org/documentation we can enforce a certain degree of  
consistency in metadata and style. Would that work for you?

Thank you for your interest!

Martin

--
(muted)



-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Martin Aspeli-2 Martin Aspeli-2
Reply | Threaded
Open this post in threaded view
|

Re: Re: Documentation effort

Hi,


>> I'm thinking we should cover
>> setting user preferences,
>
> Have it
>
>> adding of some content types,
>
> Have some, just not done yet.
>
>
> So far we have:
> how to join
> how to log in
> how to set preferences
> how to add a product

Great! My own time has been a little ocnstrained lately, but any reviewer  
on plone.org should be able to help you out.

Morten - please do co-ordinate with JoAnna so we don't duplicate effort.  
The easiest thing is probably to add you to the documentation team group  
on plone.org, and you'll be able to edit + review any documentation.

What is your plone.org username?

> This is all I've had time to do and it needs to be reviewed. I have
> some other how tos that I haven't posted yet. All of the above can be
> found under the reference manuals section on plone.org and it's called
> the Plone End User Manual. BUT, it's not published...it's hidden
> because it's still in progress.

See above.

> If someone wants to publish a to do/ need list I can start working from  
> that.
> I can do just text, text with screen shots, or AVI movies of me
> completing actual tasks (sorry, no sound or witty commentary).

Both would be very good. We had an attempt at some movies, but they fell  
through because they used a non-standard setup for screenshots, and the  
original author seemed to lose interest in tidying them up. I think  
printable text manuals should be the first priority, though.

> Right now I'm doing this on my own time. But I will be documenting
> some plone stuff here for a client in the up coming month. I can
> probably crank out a few procedures in a weekend. Contact me with a
> request and I'll work on it. First come, first serve and I'll squeeze
> it in to my free time as it becomes available.

Fantastic! :)

Martin

--
(muted)



-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Morten W. Petersen Morten W. Petersen
Reply | Threaded
Open this post in threaded view
|

Re: Re: Re: Documentation effort

In reply to this post by Martin Aspeli-2
>> The reason I'm asking here is that there's no point in us doing it, if

>> similar efforts are planned/underway.  It doesn't sound like you
>> documentation folks are doing anything like it, so it's safe for us to
>> spend some time working on documentation and a site..
>
>
> Like limi says... running code wins. demo.plone.org was a good idea
> that  got neglected. If you can provide the bandwidth (both in man-hours
> and  hosting) to get a decent demo going and demonstrate to end users
> how to  use Plone effectively, this would indeed be a very good thing
> for Plone,  and we would welcome it.
Yep.

>> Yeah - more of a step-by-step tutorial than a reference.  We're just
>> guiding users through the first steps of using Plone.
>
>
> We're lacking this, definitely. JoAnna said she wanted to help too, so
> try  to co-ordinate with her. But there is a definite market for such
> documentation.

I've got another guy (Thomas) interested in creating documentation for
Plone as well signed up on our documentation site, so maybe we can get
something going here..  Who's JoAnna?

> We'd be very grateful for this if you can offer the time to produce it
> and  keep it up to date. It would be best, however, if you can put the
> documentation up as a reference manual on
> plone.org/documentation/manual,  that'd be best - the more scattered
> documentation is, the less effective  it is, and on
> plone.org/documentation we can enforce a certain degree of  consistency
> in metadata and style. Would that work for you?

Well, I have to be selfish here - what we want to do is make money off
these articles, directly and indirectly - so we want to have them on our
site

  http://opensourcearticles.com

with all the responsibilities and benefits that brings.  Why would it be
less effective having it on another site than plone.org?  Would it be
possible to link to our articles?

-Morten

morten.vcf (304 bytes) Download Attachment
Martin Aspeli-2 Martin Aspeli-2
Reply | Threaded
Open this post in threaded view
|

Re: Re: Re: Documentation effort

>
> I've got another guy (Thomas) interested in creating documentation for
> Plone as well signed up on our documentation site, so maybe we can get
> something going here..  Who's JoAnna?

Great :)

JoAnna Springfield - she's responded to this thread. She's a  
technical writer who wants to help with end user documentation.

>> We'd be very grateful for this if you can offer the time to  
>> produce it
>> and  keep it up to date. It would be best, however, if you can put  
>> the
>> documentation up as a reference manual on
>> plone.org/documentation/manual,  that'd be best - the more scattered
>> documentation is, the less effective  it is, and on
>> plone.org/documentation we can enforce a certain degree of  
>> consistency
>> in metadata and style. Would that work for you?
>>
>
> Well, I have to be selfish here - what we want to do is make money off
> these articles, directly and indirectly - so we want to have them  
> on our
> site
>
>   http://opensourcearticles.com
>
> with all the responsibilities and benefits that brings.  Why would  
> it be
> less effective having it on another site than plone.org?  Would it be
> possible to link to our articles?

Well, ideally we want to limit the amount of fragmentation in our  
documentation, both in terms of location (and thus how easy it is to  
find) and style + metadata.

However, we do have a Link type, and your site is obviously  
"serious", so I don't think it should be a problem.

Thanks for taking an interest!



-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
JoAnna Springsteen JoAnna Springsteen
Reply | Threaded
Open this post in threaded view
|

Re: Re: Re: Documentation effort

> > I've got another guy (Thomas) interested in creating documentation for
> > Plone as well signed up on our documentation site, so maybe we can get
> > something going here..  Who's JoAnna?
>
> Great :)
>
> JoAnna Springfield - she's responded to this thread. She's a
> technical writer who wants to help with end user documentation.


Springsteen, actually but close enough. ;)
email me  at  [hidden email]

FYI: I put a bug in Limi's ear about coming up with a formal way to
request documentation. Something like the bug collector but instead
you'd submit documentation needs. I think it would be a nice way to
coordinate the process.



It would be best, however, if you can put
> >> the
> >> documentation up as a reference manual on
> >> plone.org/documentation/manual,  that'd be best - the more scattered
> >> documentation is, the less effective  it is, and on
> >> plone.org/documentation we can enforce a certain degree of
> >> consistency
> >> in metadata and style. Would that work for you?

Speaking of which, do we have an official documentation style guide?
(as it pertains to user documentation, not product or error
documentation)
If we do I haven't been following it. (sorry)
If we don't, that's something to add to the list.


> > Well, I have to be selfish here - what we want to do is make money off
> > these articles, directly and indirectly - so we want to have them
> > on our
> > site
> >
> >   http://opensourcearticles.com
> >
> > with all the responsibilities and benefits that brings.

I too one day hope to branch into some end user plone training so
doing this documentation is helping hone my plone skills. I have no
problem doing the documentation for free for plone.org because I see
it as a trade for offering the tool for free. Reciprocity if you will.
Someday I hope to be able to offer training or documentation or maybe
even a book but once I do that it will be distinctly different than
what I write for plone.org and it will be packaged under my company
name. (of course this is all dreaming at this point)

Having the documents located on plone.org does lend certain
credibility to the content. It has a more official feel to it because
it's straight from the source.
It depends a lot on the documentation you plan to offer.
It sounds like you are more focused on all the ways you could
configure the tool and what a configured end product could offer.
Whereas right now what I'm focusing on is strictly procedural
documentation. I see a huge benefit in what you'd be covering and I
know it's something that I wanted to see when I was first introduced
to plone. I also don't see in overlap in effort as of right now. I'm
sure we can figure out a way to link to the stuff you're going to
create between the two sites.
I'm inclined to say put it in plone.org but that kind of defeats the
purpose of you making money off of the ads you run as the documents
wouldn't technically be on your site. It sounds like you've found a
real niche in documentation that plone.org has yet to offer. Just
cover your bases with the plone powers that be and make sure what you
plan to do doesn't infringe on anything and you're set.

-JoAnna


-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
Morten W. Petersen Morten W. Petersen
Reply | Threaded
Open this post in threaded view
|

Re: Re: Re: Documentation effort

> Springsteen, actually but close enough. ;)
> email me  at  [hidden email]
>
> FYI: I put a bug in Limi's ear about coming up with a formal way to
> request documentation. Something like the bug collector but instead
> you'd submit documentation needs. I think it would be a nice way to
> coordinate the process.

OK.

> Speaking of which, do we have an official documentation style guide?
> (as it pertains to user documentation, not product or error
> documentation)
> If we do I haven't been following it. (sorry)
> If we don't, that's something to add to the list.

The style we use on opensourcearticles.com is very casual and friendly -
and successful.  For the audience we're targetting I think this style
will be a good fit.

> I too one day hope to branch into some end user plone training so
> doing this documentation is helping hone my plone skills. I have no
> problem doing the documentation for free for plone.org because I see
> it as a trade for offering the tool for free. Reciprocity if you will.
> Someday I hope to be able to offer training or documentation or maybe
> even a book but once I do that it will be distinctly different than
> what I write for plone.org and it will be packaged under my company
> name. (of course this is all dreaming at this point)

OK.  Sounds like a plan.  :)

> Having the documents located on plone.org does lend certain
> credibility to the content. It has a more official feel to it because
> it's straight from the source.

Yeah..

> It depends a lot on the documentation you plan to offer.
> It sounds like you are more focused on all the ways you could
> configure the tool and what a configured end product could offer.
> Whereas right now what I'm focusing on is strictly procedural
> documentation. I see a huge benefit in what you'd be covering and I
> know it's something that I wanted to see when I was first introduced
> to plone. I also don't see in overlap in effort as of right now. I'm
> sure we can figure out a way to link to the stuff you're going to
> create between the two sites.

Great - if there's no overlap, we can keep on trucking.  Thomas has just
started on the first part of the introduction, so we should have
something to show for in the next couple of weeks.

> I'm inclined to say put it in plone.org but that kind of defeats the
> purpose of you making money off of the ads you run as the documents
> wouldn't technically be on your site. It sounds like you've found a
> real niche in documentation that plone.org has yet to offer. Just
> cover your bases with the plone powers that be and make sure what you
> plan to do doesn't infringe on anything and you're set.

I think we're in a sweet spot here, as we have motivation to build and
maintain the documentation.  It will be licensed under a CC-By license

  http://creativecommons.org/licenses/by/1.0/

so if anyone wants to use it for their own purpose, they're easily able
to.  Anyone who contributes can have a link to their website listed in
the article/credits page - which is an opportunity to get customers
interested in what we're doing - training users.

-Morten

morten.vcf (304 bytes) Download Attachment