[jira] [Commented] (CB-10448) Cordova should have a styleguide

["Robert Posener (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CB-10448?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15126767#comment-15126767 ] 

Robert Posener commented on CB-10448:
-------------------------------------

Current Status

Hi all,
I have significantly revised the Cordova Document Style Guide (docs-STYLEGUIDE.md ) and it is now ready for Committer community review.
I have signed an ICLA and received a receipt acknowledgement from Craig L. Russell.
I had to read up on and learn Markdown and The Apache Way.
I have not yet learnt how to use JIRA or GitHub (forking and merging in particular) – but WILL do so in the near future.
I have attached my revised file (docs-STYLEGUIDE.md ).
Rather than everyone waiting while I read up on and learn GitHub, could someone please put my revised file into GitHub so that it may be reviewed by those interested.

I have some questions:

1. What tools are used for editing documents in Markdown?
2. Do people just edit documents in situ in GitHub?
3. Does anyone use grep to do any of the checking suggested in the current Document Style Guide?

Next Steps Strategy

To upgrade the current documentation to use the new document style standards will be a big effort.
To educate the Committer community about the new document style standards is going to be a bigger effort.
To get Committers to continue to use the new document style standards will be a bigger effort.
Overall, it is going to be a BIG organisation change (transformation) activity:

1. It will need "selling"
2. There will be push-back
3. "What's in it for me? will need to be addressed
4. It will need constant, on-going vigilance

My Proposal/Recommendation

Just as we have regression tests for our code, I would recommend:

Writing a program that reads a documentation file and checks it for as many of these rules as possible.
Then Committers and reviewers can quickly run the test program to identify any problems (it becomes just another test in the automated test suite).
I have done this once before where I developed a Microsoft Word macro to check for "imprecise" words that have no place in Requirements Specification documents (eg, "should", "could", "might", "ought", “nice”, etc) and this works very well with lots of people/companies now using it.
Such a program might take on a life of its own and become valuable to other ASF projects (and even to the wider world).
This would save much time by a lot of people and would make it easier to "sell" to Committers.
It would also allow us to remove the "grep" statements embedded in the current Document Style Guide.
Comments please?


> Cordova should have a styleguide
> --------------------------------
>
>                 Key: CB-10448
>                 URL: https://issues.apache.org/jira/browse/CB-10448
>             Project: Apache Cordova
>          Issue Type: Task
>          Components: Docs
>            Reporter: Dmitry Blotsky
>         Attachments: Document Style Standards.HTML, docs-STYLEGUIDERP2.md
>
>   Original Estimate: 48h
>  Remaining Estimate: 48h
>
> Languages it should cover:
> - JavaScript
> - Markdown
> - Java
> - Objective C
> - C#
> - JSON
> - YAML
> - CSS
> - HTML
> - English (voice, tense, etc.)
> The existing docs styleguide (https://github.com/MSOpenTech/cordova-docs/tree/master/doc) is a good starting point. Having /docs/styleguide/LANGUAGE.md is a potential way to organise it.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@cordova.apache.org
For additional commands, e-mail: issues-help@cordova.apache.org