Skip to content

Heirarchy & Misc notes #14

Closed
orta opened this Issue Apr 14, 2013 · 15 comments

5 participants

@orta
CocoaPods member
orta commented Apr 14, 2013

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:

Not so good example:

@orta
CocoaPods member
orta commented Apr 14, 2013

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
CocoaPods member
orta commented Apr 14, 2013

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

@alloy
CocoaPods member
alloy commented Apr 14, 2013

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

@supermarin
CocoaPods member

👍

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
CocoaPods member
mtitolo commented Apr 14, 2013

👍 @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
CocoaPods member
orta commented Apr 14, 2013

@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
CocoaPods member

👍 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
CocoaPods member
mtitolo commented Apr 17, 2013

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
CocoaPods member
orta commented Apr 17, 2013

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
CocoaPods member
alloy commented Apr 18, 2013

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
CocoaPods member
mtitolo commented Apr 27, 2013

@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
CocoaPods member
alloy commented Apr 29, 2013

@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
CocoaPods member
orta commented Apr 29, 2013

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

@mtitolo
CocoaPods member
mtitolo commented May 1, 2013

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

@mtitolo mtitolo closed this May 1, 2013
@orta
CocoaPods member
orta commented May 1, 2013

Ace 🌟

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.