The Git handbook, as it stands now, seems a bit out-of-order. Information that should appear as sub-pages of Getting started with Git on Drupal.org instead appears as sub-pages of Contributing code on Drupal.org. The latter is just an overview of ways to contribute code; other pages are not really sub-topics of it. Rather, the sub-pages of this page should be moved under Getting started with Git on Drupal.org. The Contributing code on Drupal.org page should also be made a child page of Getting started with Git on Drupal.org.

Here is the new book outline I propose:

This is by no means a perfect organization, but I think it provides a good starting place from which to order the handbook in a more logical, coherent manner. Thoughts?

Also, I am unable to edit the pages Contributing code on Drupal.org, Obtaining Git access, and Usage policy, I am guessing because they are using an input format to which I don't have permission (maybe Full HTML).

Comments

arianek’s picture

arianek commented

Hi Dan -

This looks great! I've given you the Docs Admin user role, which should give you access to almost all site pages (aside from some that might be very high level pages or contain legal stuff - for those, we'll have to file an issue in the webmasters queue or ping webmaster types in IRC).

I'll tweet this and see if anyone can review, and otherwise wait for Jennifer's 2 cents, and then I can probably do the rearranging (you won't have access to the book-outline admin interface).

Thanks again for stepping up to help with the git docs!

marvil07’s picture

marvil07 commented
Issue tags: +git phase 3

Adding tag so it can get some more visibility ;-)

aspilicious’s picture

aspilicious commented

Git gui tools are way to deep in the handbook

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I agree with aspilicious in #3. I've started a page on how to use Eclipse to accomplish the git workflows, but I don't know if anyone will ever find it. http://drupal.org/node/777182

As a separate question that probably shouldn't be on this issue... I noticed that there's a Doc component to the Great Git Migration issue queue. So danmuzyka - just wondering (and this is TOTALLY your call) - would you rather manage the Git doc issues there, or in the Documentation project issue queue? I think it would probably be better for you if they were all in the same place. It's easy to take an issue that's been filed in the Doc issue queue and change the component to Git.

danmuzyka’s picture

danmuzyka commented

aspilicious and jhodgdon, good to know, I hadn't even gotten that far in reviewing those sections of the documentation.

arianek, thanks for the new role! I seem to be able to edit Obtaining Git access now, but still not Contributing code on Drupal.org or Usage policy. I'll post something in the Webmasters issue queue per your suggestion.

jhodgdon, thanks for bringing to my attention the issues in the Great Git Migration issue queue. I would prefer to manage all Git documentation issues in the Documentation issue queue since that is where I am working already. Should I just start changing issues in the Great Git Migration queue with the component set to Documentation to the documentation project and tag them git and git phase 3?

I will begin making the above-suggested changes on the pages for which I have editing access. I will try to limit the amount of parent/child hierarchy, per the Online documentation structure recommendations.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Yes, go ahead and move issues over - just change the Project and voila. :)

Thanks danmuzyka!

jn2’s picture

jn2 commented

The new order looks good to me. One thing I noticed is that the second page in danmuzyka's list, Installing Git has links to three of the Windows GUI tools. That keeps it very high in the Git handbook. If those links were replaced with a link to jhodgdon's GUI page, it would solve both the problem of duplication and of getting a reference to the GUIs higher in the handbook.

eliza411’s picture

eliza411 commented

See also #1013996: [Meta] Create Structure for Git Handbook and #1040214: Reorganize Git and Contributing Code sections of Handbook I'm going to close that as a duplicate of this since this actually has a plan!

aspilicious’s picture

aspilicious commented

Srry danmuzyka and others...

I HAD to change the outlines myself as proposed here.

Why?
1) that section contained 22! subsections o_O
2) I couldn't find the info I needed
3) I made a structure in notepad before I found this again and it matches the outline proposed here + I didn't saw any 'no we can't do this'

Result!
==> 8 subsections left

TODO
==> I can't edit the FAQ, is it possible to change the format?
==> I left Authenticating with git because I thought it was a rather imprtant page and it has 3 subsections

Again, srry if I killed someone while changing this :) (if it's not ok you can revert it ;) )

aspilicious’s picture

aspilicious commented

Oh and I didn't touch git gui tools but I would like to have it under the new troubleshooting section OR in the get started section but I think it deserves a new section (also because the git gui tools will have sub-sub sections).

Can I change the outline for that?

eliza411’s picture

eliza411 commented

I changed the format of the FAQ and Contributing Code from Full html to Filtered and Documentation respectively so they should be editable now.

+1 to reorganizing the docs according to the proposed plan, at least from where I'm at. I couldn't find anything anymore either :)

aspilicious’s picture

aspilicious commented

Thnx eliza, btw I found this page

http://drupal.org/node/1042972

2 remarks
---------
1) Nobody needing this page will ever find it
2) Shouldn't this be an item in the FAQ?

EDIT
-----
This page http://drupal.org/node/1053134 has a triangle meaning it has some children, but I can't see them. Are they archived? And does an archived child count as a real child than?

eliza411’s picture

eliza411 commented

@aspilicious That page is referenced by Drupal.org itself as noted in the revision history. It could live elsewhere if you and Dan have ideas for it, but the primary method of finding it will be from the interface when privileges have been revoked. I do wish that it had more substantial content.

I don't think it is actually a frequently asked question yet as not many accounts have been revoked, but I can see the value of referencing it there.

eliza411’s picture

eliza411 commented

I don't have a solution to propose, but I do find it confusing how when the Git docs were on their own, we added a contributing code section per discussions with jhodgdon and the Git team. We were trying to make the Git docs be contained in one section and ready for the deployment. After the deployment the Git docs unit was moved into the larger menu structure also called Contributing code. Again, not sure what specifically to do about it.

I'm hoping to work on this intensely with @danmuzyaka and others on March 22 to see if we can re-impose some order here :)

Maybe, but not necessarily related, when I look for Git docs, I wish the Getting Involved guide had top level entry containing the word Git, even if it's just something like the Drupal and CVS link. Maybe it's time for that link to say Drupal and Git now.

danmuzyka’s picture

danmuzyka commented
Issue tags: +Documentation

@eliza411 and @aspilicious THANK YOU so much for working on this! I am trying to make time for this project between working two jobs, and haven't really been able to take a look at it for over a week now.

@jn2 I changed the Installing Git page per your suggestion.

@aspilicious, I had actually made some changes to the documentation outline to flatten the hierarchy of pages, relative to my original proposal at the beginning of this thread. I did that after reading the guidelines at http://drupal.org/documentation-writers-guide#hierarchical_organization. However, I'm not sure that my changes were the best approach, because it resulted in the list of pages under Getting started with Git on Drupal.org being very long. There should be a careful balance struck between too many levels of hierarchy and not enough. aspilicious, I think I like it better the way you reverted to having sandbox projects, full projects, and patches having several related child pages, rather than having the would-be child pages at the same level of hierarchy and directly beneath the overview pages for sandbox, full projects, and patches. So, thanks!

@aspilious I agree that Authenticating with Git deserves to be at the level of the book hierarchy where it currently is, and not buried somewhere. I think that is another one that I moved up in the hierarchy per http://drupal.org/documentation-writers-guide#hierarchical_organization.

@eliza411, thanks for changing permissions on the Drupal.org Git FAQ page and on Contributing code on Drupal.org. I see that Drupal.org Git FAQ was already moved (yay!), and I was just able to move Contributing code on Drupal.org myself, now. Unfortunately, I don't have permission to move Usage policy, so I have posted a request in the webmaster issue queue.

eliza411’s picture

eliza411 commented

@danmuzyaka, sorry I missed moving the FAQ. It's locked because no language can be changed without Legal's review and approval. It can, and has been, moved.

danmuzyka’s picture

danmuzyka commented

@eliza411 - Thanks for moving the Usage Policy page! I didn't realize you had access to do that.

danmuzyka’s picture

danmuzyka commented

OK, bigger question here...I was looking at Change recommended format for commit messages (no more '#1234 by abc') and realized that a lot of pages in the Git handbook and the parent Contributing Code handbook are duplicates of each other. Probably it would make sense to merge the Git handbook documentation into the larger Contributing Code documentation. Maybe I'll post another revised outline/proposal once I've had a chance to read through not only the Git documentation but also the rest of the Contributing Code handbook.

aspilicious’s picture

aspilicious commented

I looked at the section about patches last week and I (together with eliza and some others) have put all the Git specific stuff in the git handbook and left all the non Git stuff (svn, and other non Git tools) in their original place.

I agree another look at the "contribute code" section as a whole could be a nice win :)

eliza411’s picture

eliza411 commented

It's become clear since the original proposal went up that there are a lot more pages involved in this ... danmuzyka and I made a New Outline in Google Docs together, which we'll paste in here when we've gone through it a second time. It's visible at the link above, and I think it encompasses all of the changes that have been made to the Git docs.

aspilicious’s picture

aspilicious commented

Should we put the apply patches section in here? Or will it stay in the "test code" section

eliza411’s picture

eliza411 commented

We're talking about leaving a Test code page that is an overview of why that's helpful and what qualities you need, but putting the Apply patches into the Git docs.

eliza411’s picture

eliza411 commented

@aspilicious I added the Applying Patches pages to the Google Doc.

danmuzyka’s picture

danmuzyka commented
Component: Placement/Navigation/Strucure » Correction/Clarification

I made the remaining changes outlined in that Google doc today (at least, the ones where everyone is in agreement). Wondering if we can mark this issue as closed or if there are outstanding details we still need to address?

eliza411’s picture

eliza411 commented
Status: Active » Fixed

I think the reorganization is complete and it's safe to mark this fixed.

Status: Fixed » Closed (fixed)
Issue tags: -Documentation, -git, -git phase 3

Automatically closed -- issue fixed for 2 weeks with no activity.

Issue tags: +Documentation, +git, +git phase 3

Restoring issue tags, see #2125755: System messages removed all issue tags during D7 upgrade.