I would like to discuss Commons 3.x documentation - where, how, when, who...
At the moment there are two places where Commons users can find documentation:
- Commons community documentation group - login not required to view, mostly unstructured docs
- Acquia Drupal Commons documentation - login required to view, structured docs
Where, how and when?
I would like to suggest that at this point we start to gather documentation about Commons 3.x and that drupal.org distribution documentation page become official Commons community documentation home.
Why?
- We would have structured documentation that you can browse without requirement to sing up.
- It is consistent with Commons philosophy about having official development and support at drupal.org in transparent and collaborative way.
- Collaborative editing of Commons documentation on drupal.org can bring only good to Drupal/Commons community.
- Groups.drupal.org will run on Commons 3.x, so it would be nice to have all under the same *.drupal.org roof.
- Greater visibility of Drupal Commons distribution and documentation (because of drupal.org SEO karma)
- I believe there can be found more pro arguments that I can't think of at the moment. :)
Some reasons why to start making documentation right now:
- We could easily make use of structured (architecture and design) documentation for e.g. writing article about GDO for Drupal Case Studies.
- Generally, in software development documentation is as important as the software itself, and IMO it would be really nice to have good documentation as soon as Commons 3.0 is released. :)
I understand that from the business logic point of view this idea maybe doesn't sound good, but, I'm strongly convinced that this approach can only bring benefit to all involved parties.
After all, it's only logical step - why stop at providing only open source software when you can also provide open source documentation? ;)
One great example, IMO, is Omega theme official docs - and it's first result if you google omega docs.
Feedback welcome.
Comments
Comment #1
mariomaric CreditAttribution: mariomaric commentedI made some clarifications in the issue summary, also this part is better suited for comment:
Fingers crossed. :)
Comment #1.0
mariomaric CreditAttribution: mariomaric commentedFurther clarifications... -- m.m
Comment #2
Kristina Katalinic CreditAttribution: Kristina Katalinic commented+1 and will volunteer 5 hours a week
Comment #3
juan_g CreditAttribution: juan_g commentedmariomaric wrote:
Yes, although of course docs can be in the single or multiple places where distribution maintainers prefer, for drupal.org documentation of specific distributions (Commons, etc.), that's the place.
Comment #4
juan_g CreditAttribution: juan_g commentedIndeed, an advantage of drupal.org documentation is that it's community-maintained, and everyone can help to expand and improve it.
For example, when replying questions from others on groups, forums, irc, etc., we can add the info to the drupal.org docs ("edit this page" links) and, instead of repeating explanations, simply reply to next similar questions with just a link to the suitable doc, where the answer is available to all the community from that moment.
Comment #5
crimsondryad CreditAttribution: crimsondryad commentedI'd like to see the Commons docs on d.o. I appreciate all Acquia does, but if this is going to be a community distro, it needs community docs where all the other distros are documented ( ie, here ). I am also concerned that folks will be irritated by being forced to sign up ( I know I was ).
Comment #6
ezra-g CreditAttribution: ezra-g commentedThanks to everyone who has volunteered to contribute to the Commons documentation! I'm working within Acquia to figure out how to best integrate those contributions. In the meantime, feel free to file an issue for any documentation changes you'd like to see for docs that live on Acquia.com.
Comment #7
mariomaric CreditAttribution: mariomaric commentedI somehow found ezra-g's comment in #1743112: Please remove requirement to register to read the documentation linked from the project page. issue relevant to this one:
The point is, I certanly hope so, that because Commons is Open Source Drupal distribution we as a community should be able to freely start making community documentation @ d.o, right?
Of course, it would be great to integrate and connect community and official contributions, and I think this could be really easy if Acquia could provide their Commons docs under the same licence as d.o is using: http://drupal.org/node/14307
Big thanks to you Ezra for your quest to acquire Acquia blessing for this initiative. ;)
Comment #8
mariomaric CreditAttribution: mariomaric commentedHuh, OK, basing to another ezra-g's comment from above mentioned issue:
it would be definitely counterproductive and bad for Commons at large to host any kind of docs @ d.o. :(
All we can do now is to pray. :)
Comment #9
juan_g CreditAttribution: juan_g commentedDocumentation for Drupal projects is often in several places: drupal.org docs, maintainers' websites, various articles around the world wide web, paper books, slides, videos on youtube, vimeo, etc., etc... There is no need to have it restricted to just one place.
For example, formal, carefully curated documentation from Commons maintainers can still be at acquia.com.
And complementary, quickly editable -almost a la wikipedia- ;) community maintained docs such as "questions and answers" sections, etc., could be at drupal.org.
However, I think we should respect what the maintainers prefer for their project.
Comment #10
Topcheese CreditAttribution: Topcheese commented+ 1/2 Let's make it a win-win situation. Basic setup type docs on D.O and the more extensive docs on maintainers site. There is a need for both.
Comment #11
japerrySince commons is primarily developed by Acquia, and has staff dedicated to documentation, I don't see us supporting documentation on d.o at this time.
What I would recommend, if you see holes in the documentation, please bring it up in an issue, and if you have copy to contribute, the documentation team can review and update the docs site.
Comment #11.0
japerryStyling improvements -- m.m