Problem

The Getting Started guides are broken into multiple scenarios:

• OS X or Windows
• CLI or Desktop
• Android or iOS or Windows Phone

Solution

We can either break these out into separate articles or we can provide a dynamic tabbed navigation.

I'm happy with either solution as long as it's straight-forward for the user and supports perma-linking.

As it stands, the PhoneGap Documentation is adding very little value, since it's a mirror of the Cordova documentation. When Cordova was first donated to Apache, this made sense. However, now that Cordova is maturing as a product and defining it's boundaries, the PhoneGap Documentation must adapt.

This is a large over-arching issue that can be broken down as we tackle. The short list is to refactor the documentation, so that we can properly reference Cordova and set the stage for more useful PhoneGap documentation.

Use the PSD located at: https://www.dropbox.com/s/4ul36qjkb1qinvb/docs-mockup-interimhome.psd?dl=0

with the robit svg at: https://www.dropbox.com/s/jqld4ypm0035wvm/excited_robit.svg?dl=0

Currently, the only approach is to replace the existing assets. This is effective but makes upgrading the documentation tedious because Cordova also updates the assets.

Add a PhoneGap-specific directory that can override the default template assets.

git clone ...
cd phonegap-docs/
npm install
npm start

Opens my browser to localhost:3000 but never loads the page. However, I can manually access Docpad's served content from locahost:9778.

This seems to be an issue with BrowserSync. We'd like to use the library if possible, so let's look into this issue a little more.

Using code snippets with longer lines cause the content to merge into the sidebar.

Problem

By default, DocPad persists the outPath directory between builds. This means deleted files are persisted and included in new builds.

1. Callouts (shaded text or otherwise marked) for notes, warnings and tips with a sidebar color / title or icon.

   Reference ideas:

   • https://developer.mozilla.org/en-US/docs/Web/CSS/box-orient#Examples
   • http://getbootstrap.com/components/#glyphicons-examples
   • Joni’s original design mock-up for developer site

2. Panels for Examples - a titled boxed border with a space for a screenshot and example code
   Reference ideas:

   • http://getbootstrap.com/components/#glyphicons-examples (the box itself marked with EXAMPLE)

3. Code highlighting by language except for terminal (see Joni’s original mock-up).

4. Button styles for Prev / Next (float left / right in a shape that looks like an arrow or otherwise)

5. Highlight the current section of the article in the sidebar navigation when scrolling thru content

There are numbers mentions of Cordova.
"Add Platform" section should be removed.
This file needs to be updated when Docs get updated.

This request is based on the IA design requirement to allow for us to break down a page into different instructions by tab either due to tool or platform.

For example: Writing a Plugin would have tabs for iOS, Android and Windows.

Phonegap CLI docs available on 3.2 but not available on latest 3.4

Talks about phonegap (i.e. phonegap local build)
http://docs.phonegap.com/en/3.2.0/guide_cli_index.md.html#The%20Command-Line%20Interface

Talks about cordova
http://docs.phonegap.com/en/3.4.0/guide_cli_index.md.html#The%20Command-Line%20Interface

We have some folks confuse that phonegap cli is not longer supported and people suggesting to uninstall phonegap and install cordova.
http://stackoverflow.com/questions/23190127/what-happen-to-phonegap-3-4-3-3-command-line-interface

Highlight the current section of the article in the sidebar navigation when scrolling thru content

The Tutorials sidebar has enough items that it requires some scrolling if we keep this as the main point of navigation.

Problem

The current docs include a lot of great content. However, we do not plan to publish most of these articles on our first release. As the content is reviewed and polished, then we can release it.

We do not want to lose this content. We simply want to avoid including it in the production site.

Articles to consider

• Tutorials/Configure Guides
• Tutorials/Develop Guides
• Tutorials/Optimize Guides
• Tutorials/Distribute Guides

Solution

I see a few possible solutions:

1. Create a branch to backup the existing articles.
2. Move existing articles into a folder that is not rendered and published
3. Add a YAML Frontmatter option to flag drafts. published: false or draft: true.

As you can see here: https://www.dropbox.com/s/8p3x3r8dhvgpp5j/typerenderflash.mov?dl=0
I see a significant flash of unstyled text on page load (http://blog.typekit.com/2010/10/29/font-events-controlling-the-fout/)

I'm not sure, but this article: http://blog.typekit.com/2013/08/21/best-practices-for-embedding-typekit/ may provide a solution.

Add Travis-CI support to the #44 rewrite branch.

Add HTML Proofer tests to the #44 rewrite branch.

If anyone knows of a node.js version of HTML Proofer, please let me know!

Right now the sub menu disappears on mobile.

PhoneGap docs list Apache as the copyright holder and Cordova as the platform under discussion.

many parts to this issue, tracking them here:

config_ref/images.md
config_ref/index.md

Problem

Browse to:
http://stage.docs.phonegap.com/getting-started/1-install-phonegap/cli/

The content is misaligned and overlapping the navigation.

While most of the Cordova documentation is relevant to PhoneGap, there are a few areas that must be updated.

Let's list those areas here and update the generator to correct the references.

Note: this is meant to be a short-term solution. Shortly, the documentation structure and generator will be refactored.

http://docs.phonegap.com/en/edge/guide_support_index.md.html#Platform%20Support
http://docs.phonegap.com/en/edge/guide_platforms_ubuntu_index.md.html#Ubuntu%20Platform%20Guide

1. The index page (http://docs.phonegap.com/en/3.2.0/index.html) has a reference to "The Command Line Interface" but there's no link. On the other hand, the Overview page (http://docs.phonegap.com/en/3.2.0/guide_overview_index.md.html#Overview) does have a link to that page, and it works.
2. On "The Command Line Interface" (http://docs.phonegap.com/en/3.2.0/guide_cli_index.md.html#The%20Command-line%20Interface), there's no mention of how to add a platform to your project. So
3. When I create an app, the www/config.xml file has entries like and gap:splash. But the "Icons and Splash Screens" page (http://docs.phonegap.com/en/3.2.0/config_ref_images.md.html#Icons%20and%20Splash%20Screens) makes no mention of these. Neither do the "Android Configuration" or "iOS Configuration" pages.

For example: http://docs.phonegap.com/en/edge/guide_platforms_android_index.md.html#Android%20Platform%20Guide

Please, I know it's a lot of work, but this is phonegap, it's not cordova, so please make to doc to be coerent !

We need to add the ability to inject PhoneGap specific documentation.

Since Apache Cordova will be implementing a new documentation generator soon, we do not want to spend too much time engineering a solution. Something quick and dirty should suffice.

Code highlighting by language except for terminal (see Joni’s original mock-up).

Breaking up #47

It would be great if we could add one more level of navigation to be possible from the left side menu so the content can be broken down one step further in certain cases. This 3rd level could be collapsed initially to save screen real estate and expandable from an icon.

See this document for details of content hierarchy: https://docs.google.com/document/d/1jb5Ts6tvVt-W3mIWmSrjz8DkF73ODs2a4pBN055FM6w

This new addition would allow the Getting Started-->PhoneGap CLI-->Install/Create/Run level for instance.

http://docs.phonegap.com/en/edge/cordova_storage_storage.md.html#Database

1 - The changeVersion is almost NOT documented and explained in day-by-day usage
2 - the changeVersion has a differente signature call like this

db.changeVersion(oldversion, newversion, alterfunc, errorfunc, successfunc)

I learn from this blog post [http://www.raymondcamden.com/index.cfm/2013/8/14/Updating-PhoneGap-Databases] that apple website is more well documented about this method

See http://developer.apple.com/library/safari/documentation/iphone/conceptual/safarijsdatabaseguide/UsingtheJavascriptDatabase/UsingtheJavascriptDatabase.html#//apple_ref/doc/uid/TP40007256-CH3-XSW1

Quality of your doc is growing every day, please keep it growing, and update this one !
Thanks for all of your work

In documention 3.1 feature "android-package" refer to "org.apache.cordova.GeoBroker" instead of "org.apache.cordova.geolocation.GeoBroker";

Problem

At the moment, the homepage does not display the left navigation.

Add a Going Further section to the final Getting Started article to reference the Apache Cordova documentation. In future releases, we can expand this to a detail article or series of articles.

Panels for Examples - a titled boxed border with a space for a screenshot and example code
Reference ideas:

• http://getbootstrap.com/components/#glyphicons-examples (the box itself marked with EXAMPLE)

Breaking up #47

Reference:

https://twitter.com/jeresig/status/526773618374877184

Working to fix it now.

Button styles for Prev / Next (arrow shaped)

Breaking up #47

Click on any of the APIs in the left hand column of that page, all broken github links.

ex: https://github.com/apache/cordova-plugin-device-motion/blob/dev/doc/index.md

This is minor task to update the theme's Apache Cordova reference to PhoneGap.

We will hold off on updating the visual theme to match phonegap.com until later.

Clean URLs allow: path/to/file.md and path/to/file.html to become path/to/file/. This is accomplished by creating path/to/file/index.html.

Using a clean url makes referencing the documents a lot nicer, since we can drop the extension.

Callouts (shaded text or otherwise marked) for notes, warnings and tips with a sidebar color / title or icon.

Reference ideas:

• https://developer.mozilla.org/en-US/docs/Web/CSS/box-orient#Examples
• http://getbootstrap.com/components/#glyphicons-examples
• Joni’s original design mock-up for developer site

Breaking up #47

On Twitter, Lee Marrett reported that the iOS Getting Started Documentation cannot be followed step-by-step.

This could be due to differences in the PhoneGap and Apache Cordova distribution or simply that the documentation is incomplete or out-of-date.

@shazron can you review the PhoneGap documentation using the PhoneGap binary. If you discover the issue is with Apache Cordova, then we can create a JIRA issue and reference it here for tracking purposes.

Problem

There is no content on the homepage (/).

The current homepage does not display the proper navigation found in sub-directories such as:

http://stage.docs.phonegap.com/getting-started

Problem

The top of the sidebar navigation includes a link to the homepage. Previously, it was Docs Home and now it's PhoneGap Documentation.

Unless there is a reason to include this, it would be nice to have it removed. The top-left Adobe PhoneGap logo also links to the homepage, so users can still navigate back.

Environment:

Mobile Safari
iOS 8.2
iPhone 6 Plus

Steps to repro:

1. Go to the route "/guides/create" (in staging)
2. Find the first scrollable code snippet
3. Swipe it to the left to scroll the area

Expected result:

The hidden scrollable area, when revealed, is the same color as the displayed scrollable area

Actual result:

The hidden scrollable area, when revealed, is a different color from the displayed scrollable area

Screenshot

Problem

When you click on a navigation header such as Getting Started then you are taken to a page such as:

http://stage.docs.phonegap.com/getting-started

The page itself has very little content, because there are articles that describe the section in detail.

Solutions

Let's wait until the navigation is more fleshed out because it may define a simple solution. Otherwise, we can tackle it in this issue.

Use the PSD located at: https://www.dropbox.com/s/4ul36qjkb1qinvb/docs-mockup-interimhome.psd?dl=0 for reference.

We need to use this interim approach until the re-designed phonegap.com goes live.

From this page: http://docs.phonegap.com/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs

The "Plugin Registry" link. On the Cordova docs, it points to http://plugins.cordova.io

The sizing of the device images is too large for the docs content if left at full size.

Below is a screenshot from an Android Nexus 6 device using basic image markdown:

And a screenshot from an iPhone 6 device in the content using basic image markdown:

However, here's how a desktop screenshot image appears