Giving more recognition to documentation contributors

[javiereguiluz]

At SensioLabs we are always thinking about how to give more recognition to our code and documentation contributors. Now that we are redesigning the symfony.com website, we are mulling over the idea of displaying the person that contributed each documentation page.

This way, if you were reading for instance a cookbook written by @weaverryan, you could see an author box giving attribution to him. This is a quick-and-dirty mockup of how this author box could look like:

To appear in the "author box", you must have contributed at least 40% of that article. In practice, this limits the number of authors to a maximum of two per cookbook/tutorial/chapter/etc.

If you agree with this idea, we could determine automatically the authors of each documentation element using the git blame command. Alternatively, we could define a custom RST directive called authors.

[wouterj]

I like the idea. However, some concerning points (you properbly have already thought about them):

• I don't think it should be that big. Imo only a small avatar + name is enough
• I think it'll result in quite a view "wrong" authors. For instance:
  • @xabbuh, @bicpi and me have done a lot of normalizing things for the docs. That results in many blame's for us.
  • we frequently move some stuff around (translations from book to components, yaml component, class loader component, etc.). Blame will point the mover as the author of that text, while it was something else.
  • Me and @ricardclau have added tons of code blocks to have everything in all possible formats. That'll result in wrong authors since adding more formats results in many added lines (the constraint articles for instance contain 4 formats, imagine I added 3 of those formats results in around 100 extra lines)

[javiereguiluz]

@wouterj I agree with everything you said. In fact I believe that setting the author by hand is the only proper way to do it. As you have clearly demonstrated, using any automatic command would result in a lot of erroneous results.

So the next question would be: is it possible to define a custom RST directive to set the author of each article? The only thing that we need is the SensioLabsConnect username of the author because we can pull any information from it (name, avatar, bio, etc.)

[wouterj]

is it possible to define a custom RST directive to set the author of each article?

I think it's better to use the already build in directives (either docinfo or .. sectionauthor::)

[ricardclau]

+1 on the avatar being a bit too big (although it is indeed a nice way to encourage new people to contribute)
+1 as well on using RST directives because of the facts mentioned by @wouterj

A titanic work anyway

[weaverryan]

Hi guys!

Apologies - I've been traveling a bit :). I wish it could be automatic, but
you guys are right. We'll need to be careful to make sure we have the right
authors on each page, but I have no doubt we can do that fairly - we have a
good eco-system for making good, fair decisions. I think we should try the
.. sectionauthor:: or generic docinfo like Wouter suggested - it's a matter
of just being able to extract that information properly. It looks like the
info may be exposed during the build phase, but I think that would still
require a little bit of python to store it somewhere so it could be used
afterwards. Wouter, do you know anything more about that?

I think it might be nice to have more like 5 "contributors" per page (and
then make the author box a little smaller, obviously). This would let
people make medium-sized changes and still see their face up there.

Javier - are you personally working on figuring out how to extra author
info? Should we work together on this?

Thanks for taking the initiative Javier!

Ryan Weaver
US Office Head & Trainer - KnpLabs - Nashville, TN
http://www.knplabs.com http://www.knplabs.com/en
http://www.thatsquality.com
Twitter: @weaverryan

On Sun, Apr 13, 2014 at 11:19 AM, Wouter J [email protected] wrote:

is it possible to define a custom RST directive to set the author of
each article?

I think it's better to use the already build in directives (either docinfohttp://sphinx-doc.org/markup/misc.html#file-wide-metadataor ..
sectionauthor::http://sphinx-doc.org/markup/misc.html#directive-sectionauthor
)

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/3796#issuecomment-40311618
.

[xabbuh]

@weaverryan You already use something like this for the KnpLabs blog, don't you? How does it work? Is it just extracting the author out of the history of each single file?

[wouterj]

@xabbuh KnpUniversity uses the github api to get all contributors for a file afaik. Here we only want to show the contributors that brought significant changes to a file.

[weaverryan]

Yea, that's it exactly, and I think it works well if you're showing all contributors, since git does a pretty good job tracking moved files (and we don't move too many files anyways). Also, the number of commits are used for sorting contributors, which again, probably does a pretty good job most of the time. I would be ok with this solution as well - it would certainly be easier to maintain. It could be skewed by some people making many small commits, but we might be splitting hairs.

[ricardclau]

@weaverryan if the policy is still to squash commits in PRs, the many small commits problem disappears :)

[javiereguiluz]

I really like the way that Mozilla Developer Network displays the contributors for each article. See this article as example:

[weaverryan]

Yea, I think it's awesome!

[wouterj]

@javiereguiluz are you still working on this one? Do you need some help, or should we abandon this idea?

[javiereguiluz]

@wouterj unfortunately we must abandon this idea for now because it's truly complex to make it a reality.

[timglabisch]

why not just adding all icons of all participants sorted by lines of contribution like github does? this can encourage small but important contributions.

[javiereguiluz]

We want to do it (I specially do) but its too complex to tackle it right now. That's why I'm going to close this issue. We'll rethink this issue in the future.

[wouterj]

I think leaving this issue open is then a better thing, as we can use this issue to discuss ideas we get in the future.

[xabbuh]

I agree with @wouterj. Though I think this is a good reason to introduce a new "postponed" label.

[javiereguiluz]

@wouterj @xabbuh I understand your reasons for reopening this issue, but I don't agree with them.

You can't progress if you don't close issues. An open issue (specially those opened a long time ago) reminds you each and every day that there is a pending thing to do. If you have tens and tens of those issues - as we have - the psychological effect is, in my opinion, profoundly negative.

[xabbuh]

@javiereguiluz I understand what you mean. Though I disagree with such a closing policy. To me, issue should be closed only for three reasons:

1. They are invalid such like someone reports an issue which isn't an issue at all (maybe the reporter just misunderstood something).
2. Issues that are fixed: There was a pull request that has been merged and fixed the problem.
3. Things that will never be changed because for some reasons we agreed on the fact that we can't or don't want to provide a solution for an issue.

But we should not start to close issues just because we can't fix them in the short-term and closing them would make the stats nicer (to me, we would cheat ourselves with this just to get nice figures). In this case we should rather label them appriopriately (we can of course discuss if postponed is the right label for this). With this policy, people can still search for known open bug reports for certain issues, read the conversation and see that we are already aware of a problem, but won't be able to provide a solution soon.

[timglabisch]

👍 on leaving this issue open, may you can dive us a hint why this is too complex?

[javiereguiluz]

@timglabisch this is the problem to solve:

• You have to calculate the amount of lines modified by each person to decide which are the main authors of the article.
• When several people change the same line, you have to decide which one has more merit to count that line for him/her.
• You should take into account wrapping contents: when you reword some paragraph, is common to rewrap the original contents, so you are modifying lots of lines but no contents. It's not fair to count those lines as authored by that person.
• You have to take into account that changing white spaces or other minor typos shouldn't be considered for line counting.
• You have to ignore the changes made by doc managers (Wouter, Christian and Ryan ... but in the future this list could change), except when they do actually create contents.
• You have to take into account people that may change their GitHub or Connect logins to avoid duplicated people.
• You have to link GitHub user account with SensioLabsConnect account, because we want to show the photos and info of Connect profiles.
• And of course, the process of calculating this has to be super efficient, because Symfony doc has around 3 million words and it's growing rapidly.

Surely I'm forgetting about many more constraints and things that you should take into account to solve this problem rightly. All in all, I think that this is the classic problem easily solvable by humans but not by computers. If we could add an authors directive with the logins of all the people that contributed to that doc, this problem is solved. We would maintain that list manually, so all the above problems could be easily avoided.

[timglabisch]

i think even github doesnt solve most of this issues. i also dont get why you wnt to filter the doc managers, it's also "contribution".

[stof]

@timglabisch read the sentence carefully: it is about excluding them except when they actually create content. Many times, their contributions are about fixing the content to match the standards of the doc project, not about authoring the content.

[javiereguiluz]

I'm closing this old proposal as "won't fix" for the reasons stated above: it's "impossible" to do this right automatically and it's very time-consuming to do it manually. I'm sorry.