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:

  1. Commons community documentation group - login not required to view, mostly unstructured docs
  2. 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?

  1. We would have structured documentation that you can browse without requirement to sing up.
  2. It is consistent with Commons philosophy about having official development and support at drupal.org in transparent and collaborative way.
  3. Collaborative editing of Commons documentation on drupal.org can bring only good to Drupal/Commons community.
  4. Groups.drupal.org will run on Commons 3.x, so it would be nice to have all under the same *.drupal.org roof.
  5. Greater visibility of Drupal Commons distribution and documentation (because of drupal.org SEO karma)
  6. 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

mariomaric’s picture

I made some clarifications in the issue summary, also this part is better suited for comment:

I'm ready to volunteer minimum five hours per week in August documenting architecture, design and migration decisions and try to summarize and make easily available most important things from Commons D7 user stories Google docs spreadsheet - which is full of useful information, but hard reachable.

Fingers crossed. :)

mariomaric’s picture

Issue summary: View changes

Further clarifications... -- m.m

Kristina Katalinic’s picture

+1 and will volunteer 5 hours a week

juan_g’s picture

mariomaric wrote:

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.

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.

juan_g’s picture

3. Collaborative editing of Commons documentation on drupal.org can bring only good to Drupal/Commons community.

Indeed, 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.

crimsondryad’s picture

I'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 ).

ezra-g’s picture

Thanks 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.

mariomaric’s picture

I 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:

Requesting information from users who access documentation helps make it possible for Acquia to continue to invest in Drupal Commons and make it available for anyone to use for free.

The docs leads are an important way for Acquia to find additional paying projects that in turn fund Acquia's investment in the product.

I understand that this might seem counterintuitive at first, but there are a variety of ways of monitizing open source software. In this case you are exchanging registration information for the benefits of extensive engineering and design resources on an actively maintained, open platform.

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. ;)

mariomaric’s picture

Huh, OK, basing to another ezra-g's comment from above mentioned issue:

I agree that the most ideal situation would be for the documentation to live on Drupal.org, but this is also be an idealized situation because then Acquia would be unable to make the same level of investment through my time and the time of others, such as the Commons design team.

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. :)

juan_g’s picture

Documentation 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.

Topcheese’s picture

+ 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.

japerry’s picture

Status: Active » Closed (works as designed)

Since 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.

japerry’s picture

Issue summary: View changes

Styling improvements -- m.m