cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Brooks <mich...@michaelbrooks.ca>
Subject Re: Deleting Plugin Docs
Date Tue, 17 Dec 2013 17:51:26 GMT
> 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 <agrieve@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 <cmarcelk@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.

Mime
View raw message