Heirarchy & Misc notes

[orta]

Update: This will be handled with CocoaPods/guides.cocoapods.org#1.

I want to use Cocoapods

• Headline - [Screencast of adding a Podfile to an existing project
• What are Cocoapods?
• What is a Podfile?
• How do I start a new project with Cocoapods?
• How do I add Cocoapods to my existing project?
• How do I add Cocoapods to my existing project that already uses a workspace?
• Should I check in my pods folder?
• What is a Podfile.lock
• What is happening behind the scenes?
• What is the Philosophy behind cocoapods?

I want to make a Cocoapod

• Headling - [Screencast of making & setting up a library]
• How does the Specs Repo work?
• How do I update an existing Pod?
• How do I create a new Pod?
• How do I podify an existing project?
• How do I test the new Pod
• Local Pods?
• Documenting a Pod (with info about cocoadocs)
• Where can I ask questions?
• I want to create a private repository
• How do I set this up?

I want to hack on Cocoapods

• How can I contribute?
• Code Style
• Documentation Style
• Picking up Issues
• What are the main components?
• Cocoapods-core
• Cocoapods-downloader
• Cocoapods
• CLAide
• Xcodeproj

Ways to keep this sane, we will need to have:

• Formatted Code Samples
• Togglable sections of documents, to hide long bits of supplementary info

Useful navigation tools:

• Footer with overview of sections
• Chapters sidebar: like rails' documentation

Good examples:

• http://emberjs.com/guides/
• http://guides.rubyonrails.org
• http://gembundler.com ( http://gembundler.com/#learn-about )

Not so good example:

• http://backbonejs.org ( throws everything in one page, no heirarchy. Only API
  )

[orta]

General notes:

• docs.cocoapods.org -> api.cocoapods.org
• current user docs comes out to guides.
• guides.cocoapods.org ( docs.cocoapods.org could be confused with cocoadocs )

[orta]

Anyone with push access can edit the above, and I encourage it. With some discussion below.

[alloy]

This is damn fine work, Orta. I’ll respond over the coming week, right now I need to enjoy some more sun :)

[supermarin]

👍

edit: maybe a section with code-style and documentation rules would be helpful. Not sure if you've planned to include that in

• How can I contribute?

[mtitolo]

👍 @mneorr on those. Adding!

Also should be a section on doing pull requests, versus once you have push access? Not sure if that's important for public guides.

In addition, we should define a system for tagging issues and actually use it. Cocoapods/Cocoapods seems to have one, but the other repos don't.

[orta]

@mtitolo I think once the push web app is up that shouldn't pose an issue for the specs repo.

Tagging Issues system makes sense

[fabiopelosin]

👍 Terrific work @orta. I love how defined the different sections in term of user questions.

Togglable sections of documents, to hide long bits of supplementary info

I'm not sure whether I agree with this one. I would prefer to have links in dedicated pages which cover a topic in depth if needed. The documentation that you linked as good examples appear to do that.

Unfortunately, until we don't ship and app (and this might take a while) we need also a guide about how to install CocoaPods. Many users have issues with it.

[mtitolo]

I went through the current guides. Here's where I think they fit in to the new guides structure:

• Contributing to the Master Repo ~> "How does the Specs Repo work?"
• Creating and Maintaining a Pod ~> split between "How do I update an existing Pod?" and "How do I create a new Pod?"
• Creating Your Own Repository ~> "How do I create a new Pod"
• Dependency Versioning ~> ?? Somewhere in the make a pod section. Should we have a section on best practices?
• Installing Cocoapods ~> Same in Using Cocoapods
• Integrating with an Xcode Project ~> Same in Using Cocoapods, plus "what is happening behind the scenes"
• Philosophy ~> "Cocoapods Philosophy"
• Working with Teams ~> Some into "Should I check in my pod folder", otherwise, same?

[orta]

Awesome, perhaps it makes sense to try and get all this into one doc that we can edit and then start to chop out bits once the copy is in place?

[alloy]

Awesome, perhaps it makes sense to try and get all this into one doc that we can edit and then start to chop out bits once the copy is in place?

When you do that, be sure to simply delegate certain topics to @irrationalfab and me where you think it makes sense.

[mtitolo]

@orta https://gist.github.com/mtitolo/5470833 - Mainly just reformatted current guides. There are several TODOs.

@irrationalfab @alloy If either of you could help with content for the "What are the main components" section, that would be great =)

[alloy]

@mtitolo Will do. Do you think this info is intended only for developers that want to work on CP, or is it also meant for casual readers?

[orta]

Only contribution.md is for people wanting to work on Cocoapods the ruby app itself, everything else is for casual readers.

[mtitolo]

After some discussion, @orta and I agreed to move guides into a separate subdomain. This will be handled with CocoaPods/guides.cocoapods.org#1.

[orta]

Ace 🌟