As a result of numerous conversations I want to ask if people would be motivated.to help contribute to documentation if they could get badges and or karma .
This way we could somehow incentivise people to keep documentation up to date or rewrite.
and also celebrate those who do good work like that
I think any contribution should be rewarded in some way whether it be documentation, feedback or code as it makes it feel like the effort has been acknowledged/appreciated.
The single best thing I am aware of in regards to encouraging documentation updates is the addition of the Github edit button on documentation pages. Before that, I used to always try to remember to go back and submit an edit later on (which never happened) but now when I am reading the docs and spot a typo I will correct it because it is so quick and easy!
I'm inclined to agree that the initial documentation should be provided by the developer, however, in light of the comments below I think that it should perhaps then be reviewed and expanded on by someone with no knowledge of the feature so as to provide the simplest form of documentation for the uninitiated?
This subject came up at CodeCabin last weekend and we didn't really get to the bottom of it either. We had a conversation about contributing to Core and Our and what would make it easier etc.
I find contributing to the documentation really straight forward, the instructions are clear and it's easy to do. The downside is that your pull request may site for days, weeks, months before it is accepted, this can be demotivating. I hadn't realised how small the core team at HQ is and I can understand why pull requests may take time to be merged.
One thought we had was maybe Umbraco MVP's could be given authorisation to merge documentation changes, this might speed merges and encourage more people to contribute and keep the documentation up to date.
I think the entire documentation section of Our needs an overhaul and although it may not be high on the priority list for HQ, having good, easy to use documentation could encourage people to contribute to Core or Our because they can find what they are looking for. I've spent ages trawling the documentation and been sent to different parts of the site to read up about other areas e.g. API has it's own site which looks different and isn't part of the Our documentation.
I've been reading the documentation from a beginners point of view and in many cases, the documentation has been written by someone who knows the subject and so doesn't make it as simple as it could be. I hope to make small changes to the docs so that code samples are supplied where possible and make things even easier for people to follow - that's a work in progress though as I need to learn the basics first - chicken and egg scenario.
As for incentives, I think having your profile pic on the homepage is good incentive. It shows you are a contributor. I'm not sure if a badge on the forum would make me more motivated to contribute or not. Same for Karma, I'm not contributing code pull requests, I'm just updating documentation - is that worthy of karma?
I think you have to be a certain kind of person to want to contribute to the community but I do like getting a personal message of thanks from who ever merges my contribution. It's the small friendly touches that make it rewarding.
I'm not contributing code pull requests, I'm just updating documentation - is that worthy of karma?
Documentation [should be] almost as important as the code you are documenting so if forum posts and pull requests are worthy of Karma so is the documentation in my opinion!
I don't have incentives to offer currently. Just so you know: contributions to the documentation will result in a higher rank on the contribution list on the home page:
PRs for documentation are usually looked at pretty quickly and we recently have appointed someone at HQ to continually look at new PRs.
That said, if you want to rewrite something large, it's always a good idea to ask first, just like with PRs for core contributions, sometimes it just doesn't fit for us.
As for karma, I'd LOVE to make that happen, but currently we don't have an automated system linking Github to Our so it's complicated.
Is there a trick to getting your GitHub contribution showing up on that list? I ask because mine didn't.
On a more important note, are there any guides to writing whole sections/new pages. I was thinking of writing one about helpful Umbraco Deploy commands, but I don't know enough about the differences between Deploy and Courier to know if what I'm writing is Deploy or Courier related.
I've really liked the ease of updating the documentation via the 'edit' button. I also used it as a good learning experience to use Github and do changes locally as well.
It would be interesting to hear from other members of the community though to find out why they don't contribute - maybe they don't have time, maybe they don't feel they know enough to contribute.
My initial fear was I'm new and I don't fully understand the codebase yet. To update the documentation I didn't need to worry about that, I found spelling mistakes and things like that and while reading the documentation I am learning more about the code.
I've learned enough now to have a local copy of Our on my laptop and I'm digging around the code to see if I can add extra functionality to the Project search page.
A documentation styleguide sounds like a really good idea and if contributors don't adhere to it then their PR isn't merged, but if this is the case then a friendly comment on the refusal would go a long way rather than the PR just sitting there with no feedback.
Something to bear in mind if we're talking about community members providing documentation; we need to ensure that it's correct for everyone's sake, hence the suggestion of the person who wrote the code being obligated to provide docs, maybe a code pull request is rejected without documentation?
Simon's suggestion of having someone else with no knowledge of that function reviewing the doc I think is a great idea.
The other thing is ensuring some sort of uniformity amongst the docs, this will make it much easier for people to find what they're looking for, and also will help people write docs if they have a guide to follow.
Would be interesting a way to reward with karmas documentation help.
I think one step would be to investigate a way to connect Github to OurUmbraco. I'm going to look at a way to do this and share it here .
I am particularly interested in having more karmas. Here in Brazil there are few people with knowledge in Umbraco, I do a job of divulging Umbraco here with tutorials in Portuguese, manuals, etc. And with my small participation in OurUmbraco, I have been able to prove to the clients that I really understand about Umbraco, even though I have been working for more than 9 years! Showing my profile was decisive for getting projects in some cases. Another suggestion would be to have multi-language documentation. But one step at a time. And I would like to contribute to these goals and I'll investigate how to connect Github with OurUmbraco
Marcio, it could be worth speaking direct with the HQ about making the documentation section multi-lingual. I don't know how they would want to structure it but if they could provide some guidance then that would be an amazing pull request.
Thanks Marcio, there's an open pull request to link github accounts to accounts on Our Umbraco but we need to evaluate and make sure it's a good solution going forward.
We're always looking at a snapshot of the documentation at a particular point in time, and that doesn't necessarily show the great improvements that have been made in this area by Umbraco over the years.
New features are generally well documented by core team members at the point of a feature being released.
And we have documentation generated from the codebase, which previously was the best place to find how things worked!
The grey areas for me though are
the historical docs (sometimes I've come across Umbraco 6 specific advice)
Where to start as a newbie
some older code not generating documentation
and tutorials - documentation gives you detail, but tutorials give you why and how?
So what I'm saying is things are improving but the size of the task is herculean - it's easy to know new documentation needs to be added for a new feature, but not so obvious as to what areas to update when something gets obsoleted.
Where the documentation really needs help from the community is in detailed feedback, you can get some idea from common forum questions but more explicity..... What is missing? What did you specifically hope to find? What was wrong? Didn't work in latest version? and if this were visible to the community then these gaps could be filled by anyone who knew the answer or core team etc.
eg if someone reported "I just need a tutorial to step through creating a Surface Controller to handle a form post"
then there are countless people in the community who could put that together, the great thing about the docs is if someone did that, and they missed something useful, and it was reviewed by core team, and they missed the something - then someone else could add the extra bits in a future update, (eg they might not have the time to write the tutorial, but they might have the time to point out the thing) it would improve over time.
Having an Rss Feed of all updates to documents would enable people interested in maintaining the documentation to see changes and chip in, or for just people to be aware of new documentation (eg once you've checked for a thing, and it wasn't there, ... you don't check again three weeks later to see if someone has updated, you learn 'it isn't in the docs')
I created an issue on Our Umbraco for a few other ideas that would help people maintain documentation:
I haven't had time to implement any :-( but it occurs to me improving some of these things, might in the long term help documentation updates or at least that feedback loop, to keep the gradual documentation improvement focussed on what's important.
a) A list of the most commonly accessed documentation pages (need to review popular pages as stale info here causes more problems and also give us an indication of topics that are suited to Tutorials, UmbracoTV and Umbraco Training itinerys and Workshops)
b) A list of the search terms in the documentation section (What are people trying to find help on? and what terms do they use, are we 'thinking like' the people looking for help, in the provided information - also provides a hitlist of missing docs, user feedback did you find what you were looking for?)
c) A list of stale documentation, eg when was this page last updated - these pages are most likely to have been superseded as Umbraco evolves making old ways obsolete
d) Flag this page as not helpful or out of date functionality - let the people accessing the information tell us easily that the information was not relevant / missing - Top 10 of unhelpful pages...
e) Prune the issue tracker from time to time, to reflect major minor version releases / tag with prioritize (obviously this is a time thing, more the idea to try to provide information to let community focus on areas where improvement is needed most)
f) A documenters badge for contributors
g) and a 'recently updated' section / rss feed - so people can casually keep up with documentation updates, and ultimately changes in best practice that they might otherwise miss.
I like the idea of showing all documentation which is older than x months, maybe set the default to 6 months and then people can review those documents as a starting point. The older the documentation the higher priority it should have for being updated.
Incentivising Documentation
As a result of numerous conversations I want to ask if people would be motivated.to help contribute to documentation if they could get badges and or karma .
This way we could somehow incentivise people to keep documentation up to date or rewrite.
and also celebrate those who do good work like that
I think any contribution should be rewarded in some way whether it be documentation, feedback or code as it makes it feel like the effort has been acknowledged/appreciated.
The single best thing I am aware of in regards to encouraging documentation updates is the addition of the Github edit button on documentation pages. Before that, I used to always try to remember to go back and submit an edit later on (which never happened) but now when I am reading the docs and spot a typo I will correct it because it is so quick and easy!
I think whoever writes the code should also provide documentation for that code.
This means for the core code, the core team, and for pull requests, whoever submits the code.
I think this would give people the most confidence in the documentation being accurate.
I'm inclined to agree that the initial documentation should be provided by the developer, however, in light of the comments below I think that it should perhaps then be reviewed and expanded on by someone with no knowledge of the feature so as to provide the simplest form of documentation for the uninitiated?
I think that's a great idea!
I think more people might contribute if it was an easy, straightforward process.
Is it?
I would be worried that any code I contribute might not be up to scratch.
Hi,
This subject came up at CodeCabin last weekend and we didn't really get to the bottom of it either. We had a conversation about contributing to Core and Our and what would make it easier etc.
I find contributing to the documentation really straight forward, the instructions are clear and it's easy to do. The downside is that your pull request may site for days, weeks, months before it is accepted, this can be demotivating. I hadn't realised how small the core team at HQ is and I can understand why pull requests may take time to be merged.
One thought we had was maybe Umbraco MVP's could be given authorisation to merge documentation changes, this might speed merges and encourage more people to contribute and keep the documentation up to date.
I think the entire documentation section of Our needs an overhaul and although it may not be high on the priority list for HQ, having good, easy to use documentation could encourage people to contribute to Core or Our because they can find what they are looking for. I've spent ages trawling the documentation and been sent to different parts of the site to read up about other areas e.g. API has it's own site which looks different and isn't part of the Our documentation.
I've been reading the documentation from a beginners point of view and in many cases, the documentation has been written by someone who knows the subject and so doesn't make it as simple as it could be. I hope to make small changes to the docs so that code samples are supplied where possible and make things even easier for people to follow - that's a work in progress though as I need to learn the basics first - chicken and egg scenario.
As for incentives, I think having your profile pic on the homepage is good incentive. It shows you are a contributor. I'm not sure if a badge on the forum would make me more motivated to contribute or not. Same for Karma, I'm not contributing code pull requests, I'm just updating documentation - is that worthy of karma?
I think you have to be a certain kind of person to want to contribute to the community but I do like getting a personal message of thanks from who ever merges my contribution. It's the small friendly touches that make it rewarding.
Documentation [should be] almost as important as the code you are documenting so if forum posts and pull requests are worthy of Karma so is the documentation in my opinion!
I don't have incentives to offer currently. Just so you know: contributions to the documentation will result in a higher rank on the contribution list on the home page:
Oops, wasn't finished typing yet.
Other than that, we've made it super easy to start to edit any piece of documentation:
We're working on tutorials to achieve certain goals, some are here: https://our.umbraco.org/documentation/Tutorials/
PRs for documentation are usually looked at pretty quickly and we recently have appointed someone at HQ to continually look at new PRs.
That said, if you want to rewrite something large, it's always a good idea to ask first, just like with PRs for core contributions, sometimes it just doesn't fit for us.
As for karma, I'd LOVE to make that happen, but currently we don't have an automated system linking Github to Our so it's complicated.
Is there a trick to getting your GitHub contribution showing up on that list? I ask because mine didn't.
On a more important note, are there any guides to writing whole sections/new pages. I was thinking of writing one about helpful Umbraco Deploy commands, but I don't know enough about the differences between Deploy and Courier to know if what I'm writing is Deploy or Courier related.
(This was inspired by this tweet: https://twitter.com/skttl/status/908288042686980096 where those sorts of commands would be useful for developers to know (",) )
I've really liked the ease of updating the documentation via the 'edit' button. I also used it as a good learning experience to use Github and do changes locally as well.
It would be interesting to hear from other members of the community though to find out why they don't contribute - maybe they don't have time, maybe they don't feel they know enough to contribute.
My initial fear was I'm new and I don't fully understand the codebase yet. To update the documentation I didn't need to worry about that, I found spelling mistakes and things like that and while reading the documentation I am learning more about the code.
I've learned enough now to have a local copy of Our on my laptop and I'm digging around the code to see if I can add extra functionality to the Project search page.
A documentation styleguide sounds like a really good idea and if contributors don't adhere to it then their PR isn't merged, but if this is the case then a friendly comment on the refusal would go a long way rather than the PR just sitting there with no feedback.
Totally agree :-) Things like a styleguide / ideal practice would be helpful :-)
Something to bear in mind if we're talking about community members providing documentation; we need to ensure that it's correct for everyone's sake, hence the suggestion of the person who wrote the code being obligated to provide docs, maybe a code pull request is rejected without documentation?
Simon's suggestion of having someone else with no knowledge of that function reviewing the doc I think is a great idea.
The other thing is ensuring some sort of uniformity amongst the docs, this will make it much easier for people to find what they're looking for, and also will help people write docs if they have a guide to follow.
Would be interesting a way to reward with karmas documentation help. I think one step would be to investigate a way to connect Github to OurUmbraco. I'm going to look at a way to do this and share it here .
I am particularly interested in having more karmas. Here in Brazil there are few people with knowledge in Umbraco, I do a job of divulging Umbraco here with tutorials in Portuguese, manuals, etc. And with my small participation in OurUmbraco, I have been able to prove to the clients that I really understand about Umbraco, even though I have been working for more than 9 years! Showing my profile was decisive for getting projects in some cases. Another suggestion would be to have multi-language documentation. But one step at a time. And I would like to contribute to these goals and I'll investigate how to connect Github with OurUmbraco
Marcio, it could be worth speaking direct with the HQ about making the documentation section multi-lingual. I don't know how they would want to structure it but if they could provide some guidance then that would be an amazing pull request.
Thanks Marcio, there's an open pull request to link github accounts to accounts on Our Umbraco but we need to evaluate and make sure it's a good solution going forward.
We're always looking at a snapshot of the documentation at a particular point in time, and that doesn't necessarily show the great improvements that have been made in this area by Umbraco over the years.
New features are generally well documented by core team members at the point of a feature being released.
And we have documentation generated from the codebase, which previously was the best place to find how things worked!
The grey areas for me though are
So what I'm saying is things are improving but the size of the task is herculean - it's easy to know new documentation needs to be added for a new feature, but not so obvious as to what areas to update when something gets obsoleted.
Where the documentation really needs help from the community is in detailed feedback, you can get some idea from common forum questions but more explicity..... What is missing? What did you specifically hope to find? What was wrong? Didn't work in latest version? and if this were visible to the community then these gaps could be filled by anyone who knew the answer or core team etc.
eg if someone reported "I just need a tutorial to step through creating a Surface Controller to handle a form post"
then there are countless people in the community who could put that together, the great thing about the docs is if someone did that, and they missed something useful, and it was reviewed by core team, and they missed the something - then someone else could add the extra bits in a future update, (eg they might not have the time to write the tutorial, but they might have the time to point out the thing) it would improve over time.
Having an Rss Feed of all updates to documents would enable people interested in maintaining the documentation to see changes and chip in, or for just people to be aware of new documentation (eg once you've checked for a thing, and it wasn't there, ... you don't check again three weeks later to see if someone has updated, you learn 'it isn't in the docs')
I created an issue on Our Umbraco for a few other ideas that would help people maintain documentation:
http://issues.umbraco.org/issue/OUR-450
I haven't had time to implement any :-( but it occurs to me improving some of these things, might in the long term help documentation updates or at least that feedback loop, to keep the gradual documentation improvement focussed on what's important.
a) A list of the most commonly accessed documentation pages (need to review popular pages as stale info here causes more problems and also give us an indication of topics that are suited to Tutorials, UmbracoTV and Umbraco Training itinerys and Workshops)
b) A list of the search terms in the documentation section (What are people trying to find help on? and what terms do they use, are we 'thinking like' the people looking for help, in the provided information - also provides a hitlist of missing docs, user feedback did you find what you were looking for?)
c) A list of stale documentation, eg when was this page last updated - these pages are most likely to have been superseded as Umbraco evolves making old ways obsolete
d) Flag this page as not helpful or out of date functionality - let the people accessing the information tell us easily that the information was not relevant / missing - Top 10 of unhelpful pages...
e) Prune the issue tracker from time to time, to reflect major minor version releases / tag with prioritize (obviously this is a time thing, more the idea to try to provide information to let community focus on areas where improvement is needed most)
f) A documenters badge for contributors
g) and a 'recently updated' section / rss feed - so people can casually keep up with documentation updates, and ultimately changes in best practice that they might otherwise miss.
I like the idea of showing all documentation which is older than x months, maybe set the default to 6 months and then people can review those documents as a starting point. The older the documentation the higher priority it should have for being updated.
is working on a reply...