We should better document PodSpec and Podfile DSL about guides.cocoapods.org

[fabiopelosin]

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]

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

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]

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]

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]

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]

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]

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]

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]

I have a life issue orta/life#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]

Also we should document the JSON formats.

[AliSoftware]

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