> Michael - Just to clarify, you're suggesting that we put all docs-related > files *except* the main README.md within "docs/"? This plays well with > github, but wanted to clarify. Maybe translations can one day go in > docs_translated/$LANGUAGE
## project-name/README.md The file should be targeted at contributors. It can describe the project structure, dependencies, issue tracker location, etc. It should refer all users to doc/index.md. ## project-name/doc/index.md The directory should be singular, unless the other root directories are plural (bins, libs, tests, specs, etc). This contains usage information for developers using the project as a binary or library. It can contain multiple files, but there should be an index.md to indicate the starting point. This following the web convention of index.html - if you have the urge to suggest main.md or project-name.md, then please take a moment to reflect on the early web with it's attempt at main.html. Index won. All docs go in the doc/ directory. Translated docs would likewise go under doc/, not docs-translated/. We can decide on whatever convention we wish for with the translated documentation. Either doc/<lang>/ or doc/i8n/<lang>/ would make sense to me. In the case of doc/i8n/ we can make English the default at doc/<content>/, which would allow for easy HTML navigation since there would be a meaningful index.html in the root. ## Filename letter case preservation Use a hypen ( - ). Not an underscore ( _ ) and not camel-case (CamelCase). This is the UNIX convention [1] and we are following the Unix convention for all other directory names (bin, lib, src, www, etc). ## Displaying the Docs In the short-term, we can point to the GitHub rendered files. However, that puts us at the whim of Apache's ability to keep GitHub mirroring alive. In the long run, I'd rather see plugins.cordova.io supporting rendering and navigating the content of doc/. [1] http://en.wikipedia.org/wiki/Filename#Letter_case_preservation On Mon, Dec 16, 2013 at 1:22 PM, Andrew Grieve <agri...@chromium.org> wrote: > Issue created: https://issues.apache.org/jira/browse/CB-5658 > > Brian - no need to align this with plugins.cordova.io release. Until then, > we can point at the github renderings of the READMEs > > Michael - Just to clarify, you're suggesting that we put all docs-related > files *except* the main README.md within "docs/"? This plays well with > github, but wanted to clarify. Maybe translations can one day go in > docs_translated/$LANGUAGE > > Brian - "does raise the query: should plugin install automate config.xml > tags?" Not sure what your asking... > > Marcel - Definitely. > > On Sat, Dec 14, 2013 at 6:59 AM, Marcel Kinard <cmarc...@gmail.com> wrote: > >> SGTM. And where the plugin docs are removed from cordova-docs, there >> should be instructions on where consumers can find the relocated plugin >> docs.
