[
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: [email protected]
For additional commands, e-mail: [email protected]
