organization management

Author: schacon

book/06-github/images/orgs-01-page.png

@@ -45,6 +45,7 @@ From there, click the "`Add an SSH key`" button, give your key a name, paste the
 Be sure to name your SSH key something you can remember. You can name each of your keys (eg, "My Laptop" or "Work Account") so that if you need to revoke a key later, you can easily tell which one you're looking for.
 ====
 
+[[_personal_avatar]]
 ==== Your Avatar
 
 Next, if you wish, you can replace the avatar that is generated for you with an image of your choosing. First go to the ``Profile'' tab (above the SSH Keys tab) and click ``Upload new picture''.

book/06-github/images/orgs-02-teams.png

@@ -1,4 +1,4 @@
-:compat-mode:
+[[_maintaining_gh_project]]
 === Maintaining a Project
 
 Now that we're comfortable contributing to a project, let's look at the other side: creating, maintaining and administering your own project.

book/06-github/images/orgs-03-audit.png

@@ -1,46 +1,65 @@
-=== Managing an organization
-
+:compat-mode:
 [[_github_orgs]]
-==== Organizations
+=== Managing an organization
 
 (((GitHub, organizations)))
 In addition to single-user accounts, GitHub has what are called Organizations.
-Organizational accounts have a namespace where projects exist, but most other things are different.
-These accounts represent a group of people with shared ownership of projects, and they provide tools to manage subgroups of those people.
+Like personal accounts, Organizational accounts have a namespace where all their projects exist, but many other things are different.
+These accounts represent a group of people with shared ownership of projects, and there are many tools to manage subgroups of those people.
+Normally these accounts are used for Open Source groups (such as ``perl'' or ``rails'') or companies (such as ``google'' or ``twitter'').
+
+==== Organization Basics
 
 An organization is pretty easy to create; just click on the ``+'' icon at the top-right of any GitHub page, and select ``New organization'' from the menu.
 
 .The ``New organization'' menu item.
 image::images/neworg.png[The ``New organization'' menu item.]
 
-Follow the steps and you'll soon be the owner of a brand-new organization.
-As an owner, when you fork a repository, you'll have the choice of forking it to your organization's namespace, and you automatically ``watch'' any new repository created under that organization.
+First you'll need to name your organzation and provide an email address for a main point of contact for the group. Then you can invite other users to be co-owners of the account if you want to.
+
+Follow these steps and you'll soon be the owner of a brand-new organization.
+Like personal accounts, organizations are free if everything you plan to store there will be open source.
+
+As an owner in an organization, when you fork a repository, you'll have the choice of forking it to your organization's namespace. When you create new repositories you can create them either under your personal account or under any of the organizations that you are an owner in. You also automatically ``watch'' any new repository created under these organizations.
+
+Just like in <<_personal_avatar>>, you can upload an avatar for your organization to personalize it a bit. Also just like personal accounts, you have a landing page for the organization that lists all of your repositories and can be viewed by other people.
 
-===== Teams
+Now let's cover some of the things that are a bit different with an organizational account.
 
-Organizations are associated with individual people by way of teams, which are simply a set of individual user accounts.
-The power of teams comes with how they tie into other GitHub features.
+==== Teams
+
+Organizations are associated with individual people by way of teams, which are simply a grouping of individual user accounts and repositories within the organization and what kind of access those people have in those repositories.
 
-Organizations don't grant access to their repositories to _users_, they grant it to _teams_.
 For example, say your company has three repositories: `frontend`, `backend`, and `deployscripts`.
-You'd want your HTML/CSS/Javascript developers to have access to `frontend` and maybe `backend`, and your ops people to have access to `backend` and `deployscripts`.
-Teams make this easy, without having to tweak the settings for every single user.
+You'd want your HTML/CSS/Javascript developers to have access to `frontend` and maybe `backend`, and your Operations people to have access to `backend` and `deployscripts`.
+Teams make this easy, without having to manage the collaborators for every individual repository.
+
+The Organization page shows you a simple dashboard of all the repositories, users and teams that are under this organziation.
+
+[[_org_page]]
+.The Organization page.
+image::images/orgs-01-page.png[]
+
+To manage your Teams, you can click on the Teams sidebar on the right hand side of the page in <<_org_page>>. This will bring you to a page you can use to add members to the team, add repositories to the team or manage the settings and access control levels for the team. Each team can have read only, read/write or administrative access to the repositories. You can change that level by clicking the ``Settings'' button in <<_team_page>>.
 
-But that's not all teams are good for.
-Team `@mentions` (such as `@acmecorp/frontend`) work much the same as they do with individual users, except that *all* members of the team are then subscribed to the thread.
+[[_team_page]]
+.The Team page.
+image::images/orgs-02-teams.png[]
+
+When you invite someone to a team, they will get an email letting them know they've been invited and they have to accept the invitation.
+
+Additionally, team `@mentions` (such as `@acmecorp/frontend`) work much the same as they do with individual users, except that *all* members of the team are then subscribed to the thread.
 This is useful if you want the attention from someone on a team, but you don't know exactly who to ask.
 
 A user can belong to any number of teams, so don't limit yourself to only access-control teams.
 Special-interest teams like `ux`, `css`, or `refactoring` are useful for certain kinds of questions, and others like `legal` and `colorblind` for an entirely different kind.
 
-- team management
-- something else
-- guest access
-- invitations
-- how to enable ACL
+==== Audit Log
+
+Organizations also give owners access to all the information about what went on under the organization. You can go to the 'Audit Log' tab and see what events have happened at an organization level, who did them and where in the world they were done.
 
-==== Security
+[[_audit_log]]
+.The Audit log.
+image::images/orgs-03-audit.png[]
 
-- two factor authentication
-- session management
-- audit log
+You can also filter down to specific types of events, specific places or specific people.

book/06-github/sections/1-setting-up-account.asc

@@ -43,3 +43,5 @@ Take a look at https://developer.github.com[] for the complete documentation, as
   - access tokens
   - authorized applications
   - developer applications
+
+  - two factor authentiation