We should better document PodSpec and Podfile DSL

AliSoftware commented 10 years ago

The pages in the Guides are quite poor (e.g. http://guides.cocoapods.org/syntax/podspec.html only gives an example of a PodSpec).

They should be much more exhaustive, especially listing all the attributes allowed by the PodSpec DSL (and same for Podfile DSL), as we don't seem to have a complete reference of all allowed attributes anywhere.

_For example I can't seem to find any page documenting the vendored_frameworks DSL and someone searching how to reference a 3rd Party Framework in a podspec can't find a thing about that._

fabiopelosin commented 10 years ago

For example I can't seem to find any page documenting the vendored_frameworks DSL and someone searching how to reference a 3rd Party Framework in a podspec can't find a thing about that.

http://guides.cocoapods.org/syntax/podspec.html#vendored_frameworks

The documentation is derived from the comments of this file: https://github.com/CocoaPods/Core/blob/master/lib/cocoapods-core/specification/dsl.rb

AliSoftware commented 10 years ago

Oh, ok, nevermind, I didn't see the left-hand-side menu :confused:.

But still, if someone asked me about this after searching the guides, and I wasn't able to find it myself either, maybe we could find a way to better document this.

I'll assign this to me then and think about how we can improve all this maybe (a search engine in the guides could be nice, though)

fabiopelosin commented 10 years ago

I agree with you overall sentiment (also the location of that setting is far from being obvious). I don't think thug, that we should have a search engine... I would leave that to Google... just improving the description might go a long way, for example.

AliSoftware commented 10 years ago

I would leave that to Google...

The problem is that I did google for vendored_frameworks in guides, and got only 2 results:

one redirecting to the home of Guides
the other to the syntax/podspec.html page, which does not show this vendored_frameworks up front when we arrive on it (that's why I didn't even think about clicking on the "File Patterns" on the left-hand-side menu to search for it)

Maybe some better SEO and URL-Rewriting would help (e.g. clicking on "File Patterns" on the left menu should change the URL to "/syntax/podspec/file-patterns.html" so that Google can redirect directly to the right page at least?)

fabiopelosin commented 10 years ago

Confirmed on my side as well, Google always links to the root of http://guides.cocoapods.org/syntax/podspec.html and ignores the hash.

orta commented 10 years ago

hrm, yeah, as that stuff all comes from js I guess it is hard to provide google search stuff for.

This really requires a re-structuring of these pages at a pretty core level in order to make each one an individual URL. Perhaps we could move these two to a separate non-static site that is just for references like this.

AliSoftware commented 10 years ago

Improving the design by making it more clear that the menu on the left is expandable (thus "file patterns" does actually hide a submenu) would also help.

Either by adding some suggestion in the design that there is a submenu in there or by always keeping it expanded to show its submenu?

The users I see testing guides don't actually realize that there is more to it than just the page they are on, and the displayed/visible menu, thus missing a lot of information.

AliSoftware commented 10 years ago

Also I believe that the paragraph on the home page mentioning the links to the Podfile and podspec DSLs and CL-API are way too discreet

We also have you covered with references to the Podfile, the Podspec and our Command Line API.

We should make them part of the rest of the articles and not in a footnote kind of paragraph.

orta commented 10 years ago

I have a life issue https://github.com/orta/life/issues/34 about this, but doubt I'll be able to come back to the guides for quite a while.

The problem with the DSLs is that there's a large tree of information that needs to be scoped, turning it to a bunch of pages is inelegant but gets google juice and could be an option, but it basically means re-writing the whole thing.

fabiopelosin commented 10 years ago

Also we should document the JSON formats.

AliSoftware commented 9 years ago

I am officially withdrawing from this issue, because I don't know about Google SEO and how to resolve the fact that Google always link to root and all.

Note: This issue should maybe be closed so that we can reopen specific issues for the two problems? Namely:

Improve Google SEO and a way for the menu to be always open (not my expertise at all)
Document the JSON formats

CocoaPods / guides.cocoapods.org

We should better document PodSpec and Podfile DSL #7