I have posted a few changes and additions to the Prototype Git book and would like to do more, but I am having some frustration with the disorganization of the book.
In addition to a lot of duplication within the Git Book itself, there is a lot of duplication around the rest of Drupal.org's Getting Involved Guide.
For example, there are pages within that book for:
- Contribute to development - More general how-to get involved in development community and coder resources.
- Contribute code - Core vs contrib, Tips, Patches, Creating and Managing Projects, Maintainers Guide, Lots more CVS stuff
- Drupal and CVS - CVS Handbook. All over the place. All about CVS, Drupal repos, etc.
After reviewing all of the current pages and making some rough outlines, I think I have a great way to break down everything in a more user-friendly way. If we create a landing page for the book and have four horizontal blocks of links, we can make it easy to access whichever part of the handbook you need, whether you are a total noob or are already maintaining projects, but need reference.
I imagine this being a very nice page, a one stop shop for joining the development community. I remember many years ago seeing these handbooks for the first time, and having a really hard time just finding information. The disorganization makes it very hard for new users to grok our infrastructure and how the development community works.
The following is my proposed outline for reorganizing the Git Handbook and the book pages listed above.
Contributing Code on Drupal.org
Code Contributions to Drupal.org take many forms: modules, themes, translations, installation profiles, and patches... This book outlines how to contribute code and work with the drupal.org community... etc.
How to Contribute - a.k.a. Contributing Code on Drupal.org: An Overview
This should be kept very simple. Technical information should be reserved for "using git" and "using git on drupal.org". These pages should be geared towards a totally new Drupal user that may be thinking of how to contribute. It should be VERY friendly, easy to grok descriptions and link to technical details as needed.
- Usage Policy
- Sandbox Projects
- Release Projects
- Helping Others with Patches
- The Development Community - a.k.a. [[http://drupal.org/contribute/development|Contribute to development]]
Using Git
This should be kept totally Git-specific. There are many drupal.org project maintainers that just want to learn git.
- Introduction to Git
- Concepts & Command Reference a.k.a. Critical Git Concepts
- Getting Started with Git - Installing Git - Links and intro to using git on drupal.org
- Git Clients & Tools
Using Git on Drupal.org
Everything in this book assumes the user knows Git already. This will handbook will also explain how projects are created, helping users learn how to become a maintainer.
- How Drupal.org uses Git
-
Project Repo Access & Authentication - overview of Maintainership, Identify yourself to Git, Explanation of Drupal.org user and SSH Access to Git repos.
-
Examples & Walkthroughs
Maintainers Guide
This should be specifically for project maintainers. This is less technical and broad guide to how to be a good maintainer, etc.
- Basically everything from Start or maintain modules, themes, or installation profiles
- Project Release Workflow with Git
I am not officially a member of the documentation team but would like to volunteer to head up this effort. Clearer documentation would help smooth Drupal's learning curve immensely.
I look forward to your comments!
Comments
Thank you for stepping up to
Thank you for stepping up to volunteer! Once the migration work is feature complete, I'll look thoughtfully at this. Unfortunately, I'm all wrapped up in that right now. I'm tentatively planning to do a call for documentation volunteers on Monday, and it will be a priority in the days that follow. Hopefully others will step in and take a look in the meantime.
Let's get started
Thanks for your patience. This looks really good to me. I'd been working with jhodgdon on an improved structure, but I was still struggling with a) content not yet updated to reflect the organizing principles, b) the presentation of the git-specific information, c) a moving target in terms of process and product, and most recently d) no way I can continue to handle this (and I had not intended to once it got organized) and take care of my duties as PM. I'm happy to step out of the way now, especially with such a clear scheme outlined.
Would you check in with jhodgdon in IRC and set up a time to review what you've proposed? I believe her preference is to be contacted in #drupal-docs. I think what you've outlined is consistent with the discussions she and I have had.
When we put out a call for the first round of testers, I'd like to have you participate in the training because we'll be sharing a lot of detail that belongs in the docs and might not be easily found anywhere else. And really, our docs people are a part of the test team.
Finally, some of the pages are referenced in the module documentation. I don't think they're all noted yet, though. I'll try to see that they are by Tuesday so we don't cause ourselves headaches. It won't matter where they live in the hierarchy, only that they retain their focus and nid. For example, it would be good to keep the two pages referenced by http://drupal.org/node/1037478.
Again, thank you. You can find me in #drupal-gitsupport. I'll be available again on Tuesday.
Filing an issue...
Since you want to reorganize a large section of the d.o documentation, this needs to be filed as an issue in the Documentation project issue queue. I went ahead and filed one there:
http://drupal.org/node/1040214
Also I have a few comments on the proposal:
a) We should not be adding Git basics to the Handbook at all. We only want to document Drupal-specific information -- we don't want to maintain a guide to basic Git commands. We should instead link to documentation out on the web that covers this. So the "Using Git" section you propose should be dropped, in favor of just linking to external sources.
OK, I think that's the only comment I have right now. Other than this, the proposal looks OK to me.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Git usage details should be outside the handbook
I agree that details of how to use git should be outside the scope of the handbook. We want to keep it manageable. It may be that we'll need to change that policy later, but I'd really like for the handbook part to focus on the Drupal necessities, and point to the outstanding external resources that can actually cover git issues successfully.
We had made a spot for three
We had made a spot for three of the four items, so to me, the Using Git section makes sense and solves some organizational issues I'd been struggling with.
I've said this in IRC, but it's probably worth restating in a permanent location:
Although I agree in principle with re-using other instructions, especially after basic set up and workflow, the introduction of sandboxes radically changes the assumptions we can make about the skills of people interacting with version control, and I agree with careernerd's assessment that lots of resources are embedded in assumptions that are not applicable to Drupal.org and are therefore difficult for new people.
I struggled with this looking for off-site information on generating SSH keys. The Mac reference, for example, assumes you'll be managing multiple servers, intimidating and confusing noise for something that's really not too hard to do.
That said, I would prefer that we focus energy on all the areas where there's agreement. Some page is going to either hold links or basic instructions, and the structure seems generally sound.
Maybe we can revisit the conversation when we see what comes out of opening git-dev to the world for testing next week.
Also, thanks!
I forgot to say... THANKS!
You don't have to "officially" join the documentation team to be a welcome contributor. :)
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
=)
Thanks for the thanks! I actually would like to join the documentation team, since I do quite a bit of it internally at ThinkDrop.
I posted the outline first here just to get a discussion going, thanks for creating the issue!
Regarding Git usage details... I still think a few basic pages describing basic usage, with links to definitive documentation can't hurt. There is plenty of information about using CVS scattered around drupal.org, and the "CVS Instructions" tab has the commands as well.
There are a plethora of resources out there on Git, but most of them are broad and demonstrate things in a way that we don't necessarily use on Drupal.org. I've been using Git daily for more than a year now, and I still google for help instead of going to one specific resource. Most resources don't have a quick cheatsheet of commands, and since git is so flexible, most don't resemble the commands for Drupal usage.
Just some thoughts. Looking forward to hashing this out! I have some client work to do today but this evening I should have some time to jump into chat and we can talk some of this out.
thanks again, you guys are so welcoming!
~Jon
Jon Pugh
Founder & CEO
THINKDROP
open source consulting
http://thinkdrop.net
Please don't...
The CVS basics guides that we have, we shouldn't have built, and we wouldn't like to repeat this with Git. Just as the "organization" of the CVS information on drupal.org currently, we aren't looking forward to repeating with Git - we'd like to have the Git information centralized.
I think there must be resources out there on the web that give you the basics of how to install and use Git, even if it's only to type "git help" to get a list of commands, or to point to a man page somewhere? We really don't want to attempt to duplicate them, or to end up having to maintain a basics of git guide. We definitely want to give specific information about how to use Git with Drupal, if it differs from general Git philosophy.
The same philosophy is hopefully applied in our docs for MySQL, PHP, etc. For instance, we don't teach you how to program, we give you information about the Drupal programming API specifics.
Does that make sense?
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Ooops, just saw above...
I missed eliza411's comment above...
If there really is no appropriate Git information to link to, and it's too confusing to follow because of too many exceptions (like "follow this guide except omit step 4 and in step 6 change x to y"), then I agree it might be appropriate to give a guide in the d.o docs.
But what I don't want to see is a comprehensive Git tutorial, or for instance an array of pages on how to install Git on multiple platforms (since I am pretty sure installation of Git is well covered out there on the web and should not be Drupal-dependent). I'd also like to avoid duplicating any Git man pages or Git command help. We shouldn't be telling people a lot about what all the Git commands mean, but instead we should be directing them to where they can read about Git commands in general (like: Type "git help" or "man git" at the command line, or if you are really interested, here's a comprehensive git on-line manual)
We should be telling peopel hat the specific commands are in Drupal-land and what they do in regards to our processes.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
I made an attempt at a "task-based" table of contents...
I thought that was a really good idea, so I changed up the landing page at http://drupal.org/documentation/git to organize the major sub-pages according to "role", somewhat akin to what http://gitready.com/ does. I think that's what you were suggesting.
Feel free to tweak!