New Approach/SiteMap for Contribute Code [#446744]

I have gone through and read about 90% of the documentation. Add1sun says we are going to restructure some of the documents in a few weeks. A person familiar with IA will be working on this (and I will be willing to help). The documentation in the CVS section http://drupal.org/handbook/cvs is very good, though I don’t have much experience with this area. I do know that CVS Clients and GUI Tools is great!

The main problem I see is the scope and site map of http://drupal.org/node/10259 (Contribute Code). The information in this section can deal with mainly different topics such as Modules, Themes, Installation Profiles, Translations, etc...

The problem is that if I am interested in Contrib a Module then documents that contain the other topics as well as pertinent information about Module Development can be missed.

I propose a site map and different documents be placed within this section. Most of these new documents can be cut and paste from the other documents dealing with this topic. Thus making the information centralized around the users goals.

The current documentation is VERY good, and I would highly discourage people deleting this content. It has allot of valid information that can be used in new documents! Most of it is in such great shape that simply cut and pasting from the existing documents can fulfill most current documents.

I would like to propose a site map of

Contribute code
Core
Modules
Themes
Install Profiles
Documentation

Things that have no Home
Raising money (reverse bounty)

I also propose that Apply for CVS Access be divided into the above sections. Each CVS Access document will be targeted to its parent. So users who want to contrib a Module will get customized information on how to fill out the application. I hope this will lesson the burden on the CVS maintainers and also improve the success rate for applicants to be approved!

The rest of the documents can be sub divided into sub sections of into more common sections that are referenced were needed.

Comments

Comment #1

dww

we/he/they

commented 28 April 2009 at 01:00

I'll be interested in seeing how this turns out. My biggest concern with this proposal is that the CVS instructions themselves are completely independent of what you're trying to contribute. It's not clear from your proposal how that's going to work...

Once upon a time, webchick and I re-wrote/re-organized nearly the entire CVS handbook (it was right when we deployed the release system). At that time, the primary organizing concept was that there were 2 main audiences for those documents:

1) People trying to checkout code in Drupal CVS as users/consumers.

2) People trying to maintain code in Drupal CVS as contributors.

Everything was considered through that perspective -- and every page had a target audience. Some things were relevant to everyone, and others only relevant to one group or the other. The actual layout of the documentation mirrored this -- there was general CVS stuff, "read-only" CVS details, and "read/write" CVS details, in that order.

Since that time, the CVS documentation has been split up and reorganized in various ways. While I'm thrilled to see people taking initiative to try to improve things, frankly, the end result is that the above organization seems to be lost, and I can no longer find what I'm looking for when I'm trying to point people to specific areas of the handbook. :(

I no longer understand the "game plan" for the CVS documentation, and therefore, I don't really know how to try to improve things anymore, since the current organization doesn't make much sense to me. I'm obviously completely biased, and maybe most people find it easier to follow in this layout. ;)

Anyway, I'd like to understand the "point" of your changes, before talking about the specific changes themselves. So far, from what I understand, you're saying that you think the documentation about developing and contributing modules is too spread out and too many pages are talking about that *and* themes and translations, etc. You think everything would be better if the documentation was organized around what kind of code you're trying to contribute. Is that an accurate summary? If so, my concerns are:

A) how does the CVS handbook fit in?
B) how about the info about maintaining projects and releases on d.o?
...

Basically, how do people understand the general picture and find the information that's true across all kinds of contributions vs. the (AFAICT, relatively minor) subset of the documentation that's specific to each kind of contribution?

Thanks,
-Derek

Comment #2

MGParisi commented 28 April 2009 at 02:40

Cross Topics.

The major problem is that everything is spread out among 3 different areas. The CVS pages are the best and very well constructed. They *seem* complete, though Im not positive because I do not know all of the tools and ways to do things (Im a Tortoise user). Then there is the Coding Standards Section. And then there is this section http://drupal.org/node/10259!

It seems to me that this last section is a beginners guide to Contrib to Drupal! It should probably be left simple, and with resources well defined. There is so much going on in these documents that I go crazy!

The site map I proposed is a SUGGESTED replacement for the way we give information to people who want to Maintain Projects and Releases. I believe this should remain separate from CVS, and that references to CVS should be limited or simply references to the CVS handbook. In fact when someone pointed me to the CVS handbook, I was FINALLY able to get the info I needed. I do not want to tackle the CVS handbook, and for the most part CVS handbook is very good (I made some minor changes to it) but for the most part you can find the information rather easily.) I love the CVS documentation.

The problem is that there is Development information (Comments, Install Files, Drupal Standards), CVS Information, and many other information within the pages under http://drupal.org/node/10259

Its a big soup of information! I don't feel comfortable going through and deleting all that I think should go!

For instance these two documents deal with the same topic
http://drupal.org/node/23789
http://drupal.org/node/363367

Also
http://drupal.org/node/363367
Deals with so many unrelated topics.

The issue we face is that if we keep too much info in a page, no one will read it, or they wont find the important info they need in the big pile. If we do not include enough info then we wont get people to fill out the CVS ACCESS form completely, and the CVS maintainers go crazy! I personally feel as a hole, that this is all out of control!

I just don't see any organization or scope! Its basically like a dumping ground of info! I also believe that this is a very important part of the site! People wont contrib its too much work, and learning to dev in drupal is a task in itself. We need to make CVS and Contrib details as simple as possible.

I would love to take small steps, but I do not feel that I have the level of permission to go as far as I want... I also do not have access...

Comment #3

dww

we/he/they

commented 28 April 2009 at 06:08

From the very first line of http://drupal.org/node/363367:

"Status: Work in progress. Contact sun (tha_sun on IRC) to discuss this page."

Comment #4

MGParisi commented 28 April 2009 at 07:41

Well 363367 is a dead link. Thanks for pointing this out, seems to be that he fixed this or did something with this +1 to dww..

Seems some other work has been done on these pages... Its really getting much better! Good Work:)

Now

http://drupal.org/node/100748
http://drupal.org/node/262432
http://drupal.org/node/112902

I think it should be moved to the CVS section. The instructions are limited because it only deals with one way to contribute to CVS. People like me with Tortoise need other instructions. Thats why I think these instructions should be added to the CVS pages, and a reference put in its place! When I saw these instructions I stopped in my tracks. I had no way to do what they were asking, and they were offering no other solutions then command line cvs! This is single biggest reason it took me so long to finally publish my changes! I got stuck on these sections, and did not think that there was more instructions. Ofcourse now they moved CVS into the same section, which helps, but before today that was not the case. Even so, I probably would of gotten stuck, frustrated, and gave up once again. Today I got stubborn and told myself that CVS was NOT going to beat me!

http://drupal.org/handbook/cvs/clients

Deals with these topics per utility! However the clients page does not specify details about project type (as far as I can see) I will look into this further!

From the major changes I am seeing, it looks like a new site map or any major changes wont be needed. Simplification and Document removal, re-organization seems to be doing the job:)

Comment #5

dww

we/he/they

commented 28 April 2009 at 07:18

http://drupal.org/node/363367 is not dead, it was just because I used a : at the end of it, and the auto-turn-things-into-links filter messed up. ;)

Comment #6

MGParisi commented 28 April 2009 at 07:37

People are working on these pages, and the results are fantastic. Its nice to see! I have been keeping upto date with the whole section, reading it over and over again to remove/improve/add what I can.

Comment #7

dww

we/he/they

commented 28 April 2009 at 08:07

@MGParisi: I'm going to have to disagree with part of #4... There are specific pages dealing with the details of various client tools to show you how to "translate" command-line instructions and tasks into specific tools. However, it's completely unworkable for the rest of the handbook to give every example for every possible tool. That'd be a complete nightmare. The basic policy we had has been "document everything as if you're using the command-line (which many contributors and end-users in fact use), but provide pages for each tool for people who are using a GUI ".

Maybe the solution is that we should have a block which shows up on every page under http://drupal.org/handbook/cvs which links to all the client-specific CVS pages, with a little descriptive text explaining this policy. Something like:

All examples assume the CVS command line.
If you are using another CVS client, the pages
below explain how to perform any given task
for each specific client.

Also, you're once again blurring the distinction between the "general stuff about CVS" and the "specific stuff for people maintaining projects on d.o". Some of the pages you link in #4 are specifically "quickstart" guides for people to get up to speed on how to contribute without having to necessarily read and understand the entire (fairly verbose) CVS handbook (which you might consider the complete reference manual for d.o's usage of CVS). I don't think moving these into the CVS section necessarily helps. Maybe we just need the block I'm proposing here to show up on these pages, too...

Comment #8

MGParisi commented 1 May 2009 at 10:25

I actually appreciate your disagreement. I dont have the illusion of having the answers. But I think thats the purpose of this, to find out the answers.

The CVS section is hardly a complete guide. It really is a quick start guide. These tools are incredibly complicated. So complicated that many of them have books, and their documentation is the size of reasonable book.

The information I needed was here... http://drupal.org/node/188988 Hardly a complete resource. If you look at the rest of the tools you will find the same type of quick use solutions. The Command Line CVS can also contain the same information, but it is missing, and instead is found in these other documents. I don't think this is the right way to do it. I would say to move the command line CVS instructions found in thoose documents into Command Line CVS and then remove all that extra text and link to the specific tool that you use. I feel this will make things easier to consume and less daunting. Also for people like me (who dont use the command line) we wont hit a road block.

Your solution addresses the roadblock issue, but what about the fact that this amount of text within these documents dedicated to Command Line CVS does not help the rest of the document. Also, what about the person who looks for the Command Line information under CVS but finds little to no information within these sub sections?

I know I missed one, Im sorry, if anyone can find them... please post them so that we have a single reference for everything in this section that needs work?