You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Diana Shannon <sh...@apache.org> on 2002/07/01 14:33:42 UTC
[doc] policy for authorship credit
I need your input on how to think about bylines Cocoon docs, both
community-contributed and core docs (soon to be patched by new
volunteers).
I'm struggling to understand how to credit the efforts of people who
make the docs better. This effort doesn't always equate to authorship,
that is, you can spend hours editing a doc (I have) but not necessarily
contribute a substantial amount of new content. Still, the doc is better
as a result of your effort. I also want to avoid problems down the road
when users patch docs and add their name as an author, even when they
may have only contributed a single sentence. In other words, I want to
reward bylines to people who take the first step of authoring a new doc
or who add substantial amounts of additional content. Writing is hard.
Patching (what someone else started) is often a lot easier. Example:
lots of patches were submitted for XMLForm How-To. No patches yet for
new How-Tos.
Forrest introduces a revision content section. I like it. For an
example, check out this document and look at the revision history
section (at the bottom of the page):
http://xml.apache.org/forrest/primer.html
I think crediting individuals (committers as well as volunteers) for
their patches in a Revision History section -- and not necessarily in
the byline area, unless they are a co-author or add significant amounts
of new content -- is the best way. It also serves as a meaningful record
for users about updates to docs (i.e. how many users check cvs log
info?). Some users have the mistaken understanding that core docs aren't
being updated. This would demonstrate to them clearly what is going on.
It would also visibly reveal documents which may need to be updated.
I experimented with this approach in the How-To I created for the
Paginator Transformer. I didn't write it originally, Stefano did on this
list, so I gave him credit in the byline. However, I put a lot of time
editing, restructuring, testing, debugging, adding samples, etc. so I
noted my work in the revision section. Stefano has since updated the
samples, so I will add another item to the revision section, noting his
work. When users start reading the How-To, perhaps they will begin to
appreciate the effort that goes into creating a good doc...
Although I really don't like bylines at all in this context, especially
for core docs, I think we need to keep them as an incentive for new
authors to contribute docs (i.e. get "rewarded" with some visibility for
their effort). It also gives them the incentive to maintain their
contribution, because their name is publicly associated with the work.
What do you think?
-- Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Stefano Mazzocchi <st...@apache.org>.
Diana Shannon wrote:
>
> I need your input on how to think about bylines Cocoon docs, both
> community-contributed and core docs (soon to be patched by new
> volunteers).
>
> I'm struggling to understand how to credit the efforts of people who
> make the docs better. This effort doesn't always equate to authorship,
> that is, you can spend hours editing a doc (I have) but not necessarily
> contribute a substantial amount of new content. Still, the doc is better
> as a result of your effort. I also want to avoid problems down the road
> when users patch docs and add their name as an author, even when they
> may have only contributed a single sentence. In other words, I want to
> reward bylines to people who take the first step of authoring a new doc
> or who add substantial amounts of additional content. Writing is hard.
> Patching (what someone else started) is often a lot easier. Example:
> lots of patches were submitted for XMLForm How-To. No patches yet for
> new How-Tos.
>
> Forrest introduces a revision content section. I like it. For an
> example, check out this document and look at the revision history
> section (at the bottom of the page):
> http://xml.apache.org/forrest/primer.html
>
> I think crediting individuals (committers as well as volunteers) for
> their patches in a Revision History section -- and not necessarily in
> the byline area, unless they are a co-author or add significant amounts
> of new content -- is the best way. It also serves as a meaningful record
> for users about updates to docs (i.e. how many users check cvs log
> info?). Some users have the mistaken understanding that core docs aren't
> being updated. This would demonstrate to them clearly what is going on.
> It would also visibly reveal documents which may need to be updated.
>
> I experimented with this approach in the How-To I created for the
> Paginator Transformer. I didn't write it originally, Stefano did on this
> list, so I gave him credit in the byline. However, I put a lot of time
> editing, restructuring, testing, debugging, adding samples, etc. so I
> noted my work in the revision section. Stefano has since updated the
> samples, so I will add another item to the revision section, noting his
> work. When users start reading the How-To, perhaps they will begin to
> appreciate the effort that goes into creating a good doc...
>
> Although I really don't like bylines at all in this context, especially
> for core docs, I think we need to keep them as an incentive for new
> authors to contribute docs (i.e. get "rewarded" with some visibility for
> their effort). It also gives them the incentive to maintain their
> contribution, because their name is publicly associated with the work.
>
> What do you think?
*BIG* +1
I think you had a great idea. Maybe a visible location for changes is
*exactly* what is missing between the visibility of writing code and
writing docs.
Thanks for pointing this out.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Christian Haul <ha...@dvs1.informatik.tu-darmstadt.de>.
On 01.Jul.2002 -- 08:33 AM, Diana Shannon wrote:
> I need your input on how to think about bylines Cocoon docs, both
> community-contributed and core docs (soon to be patched by new
> volunteers).
I for my part wouldn't mind a list of authors and contributors to docs
in a single file and to remove them from the particular docs
altogether. IMHO "authorship" with code is useful because I know who
to bug for information :-) Perhaps an internal attribute who feels
responsible for a particular document would suffice.
Chris.
--
C h r i s t i a n H a u l
haul@informatik.tu-darmstadt.de
fingerprint: 99B0 1D9D 7919 644A 4837 7D73 FEF9 6856 335A 9E08
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by "Andrew C. Oliver" <ac...@apache.org>.
>
> The first author is the creator, and then the others.
+1
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Diana Shannon wrote:
>
> On Monday, July 1, 2002, at 08:39 AM, Nicola Ken Barozzi wrote:
>
>> Personally in the projects I do on krysalis I simply add the person to
>> the authors.
>
> You know, personally, I like to share credit as much as possible, even
> when I do most of the work. It's easy to do, it's free to give, and for
> the most part, everyone benefits. But not everyone thinks this way.
Yes, someone says that if the patch is not *substantial*, it should not
get credits.
Well, let me say that if it's not of any use, it wouldn't be committed
anyways.
If id does something usefull, then it's important as any.
In a car, what is more important, the steering wheel or the motor?
>> A one-line patch can be more important than the file itself, and
>> making the committer make the decision is not predictable enough.
>
> Of course, but not always. Unfortunately, it gets subjective. I'm trying
> to figure out what's fair.
That's why making someone decide gets tricky.
The rule "one patch, you get your name appended" is easy and air enough
IMHO.
>> The first author is the creator, and then the others.
>
> So, you are proposing anyone who submits a patch -- regardless of how
> substantive -- gets added to the list of authors, after the creator?
Yes.
>I
> assume you are ok with the idea that revision content would still be
> useful.
Well, if we have revision, it's implied that the creator(s) are the
authors, and then the revisors.
By putting them all in authors, we are just saying that the first is the
author, so it's the same.
The important thing IMHO is that when you edit, your name gets listed
in sequence after the ones that created-edited before you.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Diana Shannon <sh...@apache.org>.
On Monday, July 1, 2002, at 08:39 AM, Nicola Ken Barozzi wrote:
> Personally in the projects I do on krysalis I simply add the person to
> the authors.
You know, personally, I like to share credit as much as possible, even
when I do most of the work. It's easy to do, it's free to give, and for
the most part, everyone benefits. But not everyone thinks this way.
> A one-line patch can be more important than the file itself, and making
> the committer make the decision is not predictable enough.
Of course, but not always. Unfortunately, it gets subjective. I'm trying
to figure out what's fair.
> The first author is the creator, and then the others.
So, you are proposing anyone who submits a patch -- regardless of how
substantive -- gets added to the list of authors, after the creator? I
assume you are ok with the idea that revision content would still be
useful.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Diana Shannon wrote:
...
> Although I really don't like bylines at all in this context, especially
> for core docs, I think we need to keep them as an incentive for new
> authors to contribute docs (i.e. get "rewarded" with some visibility for
> their effort). It also gives them the incentive to maintain their
> contribution, because their name is publicly associated with the work.
>
> What do you think?
Personally in the projects I do on krysalis I simply add the person to
the authors.
A one-line patch can be more important than the file itself, and making
the committer make the decision is not predictable enough.
The first author is the creator, and then the others.
But I repeat, this is my VHO.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Diana Shannon <sh...@apache.org>.
On Monday, July 1, 2002, at 08:44 AM, Steven Noels wrote:
> We could add some (non-required) CMS revision elements/attrs to the
> document>header element and generate the revision history automatically
> at the bottom of the page. An idea for Forrest, perhaps?
Yes, of course.
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Steven Noels <st...@outerthought.org>.
Diana Shannon wrote:
> I need your input on how to think about bylines Cocoon docs, both
> community-contributed and core docs (soon to be patched by new volunteers).
>
> I'm struggling to understand how to credit the efforts of people who
> make the docs better. This effort doesn't always equate to authorship,
> that is, you can spend hours editing a doc (I have) but not necessarily
> contribute a substantial amount of new content. Still, the doc is better
> as a result of your effort. I also want to avoid problems down the road
> when users patch docs and add their name as an author, even when they
> may have only contributed a single sentence. In other words, I want to
> reward bylines to people who take the first step of authoring a new doc
> or who add substantial amounts of additional content. Writing is hard.
> Patching (what someone else started) is often a lot easier. Example:
> lots of patches were submitted for XMLForm How-To. No patches yet for
> new How-Tos.
+1 (after having spent 1.5 days authoring the little primer mentioned
underneath - I'm a slow writer)
> Forrest introduces a revision content section. I like it. For an
> example, check out this document and look at the revision history
> section (at the bottom of the page):
> http://xml.apache.org/forrest/primer.html
please bear in mind that this has been done manually, and for exact the
same reasons as you are mentioning: Ross had been doing _considerable_
editing and rephrasing on that document.
> I think crediting individuals (committers as well as volunteers) for
> their patches in a Revision History section -- and not necessarily in
> the byline area, unless they are a co-author or add significant amounts
> of new content -- is the best way. It also serves as a meaningful record
> for users about updates to docs (i.e. how many users check cvs log
> info?). Some users have the mistaken understanding that core docs aren't
> being updated. This would demonstrate to them clearly what is going on.
> It would also visibly reveal documents which may need to be updated.
>
> I experimented with this approach in the How-To I created for the
> Paginator Transformer. I didn't write it originally, Stefano did on this
> list, so I gave him credit in the byline. However, I put a lot of time
> editing, restructuring, testing, debugging, adding samples, etc. so I
> noted my work in the revision section. Stefano has since updated the
> samples, so I will add another item to the revision section, noting his
> work. When users start reading the How-To, perhaps they will begin to
> appreciate the effort that goes into creating a good doc...
>
> Although I really don't like bylines at all in this context, especially
> for core docs, I think we need to keep them as an incentive for new
> authors to contribute docs (i.e. get "rewarded" with some visibility for
> their effort). It also gives them the incentive to maintain their
> contribution, because their name is publicly associated with the work.
>
> What do you think?
>
+1
We could add some (non-required) CMS revision elements/attrs to the
document>header element and generate the revision history automatically
at the bottom of the page. An idea for Forrest, perhaps?
</Steven
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org stevenn@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [doc] policy for authorship credit
Posted by Heidi Brannan <he...@kutcha.org>.
At 08:33 AM 01/07/2002 -0400, you wrote:
>I need your input on how to think about bylines Cocoon docs, both
>community-contributed and core docs (soon to be patched by new volunteers).
>
>I'm struggling to understand how to credit the efforts of people who make
>the docs better. This effort doesn't always equate to authorship, that is,
>you can spend hours editing a doc (I have) but not necessarily contribute
>a substantial amount of new content. Still, the doc is better as a result
>of your effort. I also want to avoid problems down the road when users
>patch docs and add their name as an author, even when they may have only
>contributed a single sentence. In other words, I want to reward bylines to
>people who take the first step of authoring a new doc or who add
>substantial amounts of additional content. Writing is hard. Patching (what
>someone else started) is often a lot easier. Example: lots of patches
>were submitted for XMLForm How-To. No patches yet for new How-Tos.
+1 It took me a week to figure out how XMLForms worked and to write up the
doc as I'm new to Java being a PHP programmer. I think it is fair to be
credited for what you have done.
>Forrest introduces a revision content section. I like it. For an example,
>check out this document and look at the revision history section (at the
>bottom of the page):
> http://xml.apache.org/forrest/primer.html
+1 I like this too! Everyone who contributes should get a credit.
Heidi
>I think crediting individuals (committers as well as volunteers) for their
>patches in a Revision History section -- and not necessarily in the byline
>area, unless they are a co-author or add significant amounts of new
>content -- is the best way. It also serves as a meaningful record for
>users about updates to docs (i.e. how many users check cvs log info?).
>Some users have the mistaken understanding that core docs aren't being
>updated. This would demonstrate to them clearly what is going on. It would
>also visibly reveal documents which may need to be updated.
>
>I experimented with this approach in the How-To I created for the
>Paginator Transformer. I didn't write it originally, Stefano did on this
>list, so I gave him credit in the byline. However, I put a lot of time
>editing, restructuring, testing, debugging, adding samples, etc. so I
>noted my work in the revision section. Stefano has since updated the
>samples, so I will add another item to the revision section, noting his
>work. When users start reading the How-To, perhaps they will begin to
>appreciate the effort that goes into creating a good doc...
>
>Although I really don't like bylines at all in this context, especially
>for core docs, I think we need to keep them as an incentive for new
>authors to contribute docs (i.e. get "rewarded" with some visibility for
>their effort). It also gives them the incentive to maintain their
>contribution, because their name is publicly associated with the work.
>
>What do you think?
>
>-- Diana
>
>
>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
>For additional commands, email: cocoon-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org