Updating contribution guides for docs. #325

dobooth · 2019-04-01T18:49:34Z

This PR adds a DOCUMENTATION_TEMPLATE that describes how to contribute docs and gives a few markdown examples.
I updated the CONTRIBUTORS file to link to the new doc.

MFTF 2.3.13 - Merge Develop to Master

MFTF 2.3.14 - Merge develop to master

coveralls · 2019-04-01T20:11:28Z

Coverage increased (+1.6%) to 55.958% when pulling eaa1d0e on magento-devdocs:db_contributions into 958e9c3 on magento:develop.

dshevtsov · 2019-04-01T19:42:51Z

.github/CONTRIBUTING.md

@@ -40,7 +40,7 @@ All contributors are required to submit a click-through form to agree to the ter

   - Unit/integration test coverage
   - Proposed documentation update.
-     For the documentation contribution guidelines, see [DevDocs Contributing][devdocs].
+     For the documentation contribution guidelines, see [DOCUMENTATION_TEMPLATE][].


Suggested change

For the documentation contribution guidelines, see [DOCUMENTATION_TEMPLATE][].

For the documentation contribution guidelines, see [documentation template][].

No need to use code-like letter case because it is not related to a file name or any other entity unless it is intended to be a reference for DOCUMENTATION_TEMPLATE.md.

It is a ref to it.

no, it refers to .../.github/CONTRIBUTING.md in link definitions

dshevtsov · 2019-04-01T19:43:47Z

.github/CONTRIBUTING.md

@@ -160,7 +160,7 @@ Label| Description
 [create issue]: https://help.github.com/articles/creating-an-issue/
 [create pr]: https://help.github.com/articles/creating-a-pull-request/
 [Definition of Done]: https://devdocs.magento.com/guides/v2.2/contributor-guide/contributing_dod.html
-[devdocs]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.html
+[DOCUMENTATION_TEMPLATE]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.html


Suggested change

[DOCUMENTATION_TEMPLATE]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.html

[DOCUMENTATION_TEMPLATE]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.md

.github/DOCUMENTATION_TEMPLATE.md

dshevtsov · 2019-04-01T19:55:32Z

.github/DOCUMENTATION_TEMPLATE.md

+This page describes the process for submitting docs and serves as a template so that docs are written properly.
+
+The contribution workflow for docs is the same as submitting code.
+To contribute to MFTF docs:


Suggested change

To contribute to MFTF docs:

dshevtsov · 2019-04-01T21:18:41Z

.github/DOCUMENTATION_TEMPLATE.md

+- One space after the dash.
+- Blank line before and after list.
+
+## Code Samples


Suggested change

## Code Samples

## Code samples

You're breaking your own rule above.

.github/DOCUMENTATION_TEMPLATE.md

dshevtsov · 2019-04-01T21:24:39Z

.github/DOCUMENTATION_TEMPLATE.md

+## Code Samples
+
+For formatting and code coloring, wrap code samples in the following format.
+Replace the `xml` with the file extension of the code sample type. Use `bash` for command-line text.


Suggested change

Replace the `xml` with the file extension of the code sample type. Use `bash` for command-line text.

Replace the `xml` with the corresponding language (tupe) of the code sample. Use `bash` for shell commands and `terminal` for terminal output.

move this line after the example code block

dshevtsov · 2019-04-01T21:31:37Z

.github/DOCUMENTATION_TEMPLATE.md

+| Colume 1 text | Column 2 text|
+| Column 1 text | Column 2 text|
+
+Markdown tables work for simple tables. If you need lists or other complex features within a cell, you may have to use a HTML table.


Suggested change

Markdown tables work for simple tables. If you need lists or other complex features within a cell, you may have to use a HTML table.

Markdown formatting works for simple tables. It does not support multiline content within a cell, or split/merged cells within a row or column.

We don't want to use complex tables. The content that requires a complex table should be restructured to avoid it.

dshevtsov · 2019-04-01T21:32:32Z

.github/DOCUMENTATION_TEMPLATE.md

+## Other tips
+
+- Use spaces instead of tabs.
+- One empty line between content. No duplicate empty lines.


Suggested change

- One empty line between content. No duplicate empty lines.

- Do not duplicate blank lines.

dshevtsov

Review the suggested changes

…ing-framework

Co-Authored-By: dobooth <[email protected]>

.github/DOCUMENTATION_TEMPLATE.md

dshevtsov · 2019-04-05T19:45:53Z

.github/DOCUMENTATION_TEMPLATE.md

+
+Any changes to the Table of Contents will need to be made in the regular [devdocs repo][].
+
+## Ordered lists - all heading have a blank line before and after, capitalize the first word only


Move the rule all heading have a blank line before and after, capitalize the first word only to a section content from the heading to be consistent throughout the document.

@dobooth Any updates on this?

dshevtsov · 2019-04-15T18:43:06Z

.github/DOCUMENTATION_TEMPLATE.md

+We will inform you if it needs any additional processing.
+
+The documentation in this repository is used as the source for the [MFTF documentation][].
+Any changes to the Table of Contents will need to be made via a separate PR in the regular [devdocs repo][].


As a developer who is contributing to this repository, how do I know what Table of Contents is this sentence about? There is no Table of Contents here.

Change "repo" to "repository", "PR" to "pull request". Avoid abbreviations.

As a code contributor, I do not know what is devdocs.

dshevtsov · 2019-04-15T18:43:13Z

.github/DOCUMENTATION_TEMPLATE.md

+
+The contribution workflow for the Magento functional testing framework (MFTF) documentation is the same as submitting code.
+
+1. Create a branch from the `develop` branch in the [MFTF repo][].


Change "repo" to "repository". Avoid abbreviations.

I am slowly learning.

dshevtsov · 2019-04-16T18:40:41Z

.github/DOCUMENTATION_TEMPLATE.md

@@ -0,0 +1,66 @@
+# How to contribute to MFTF docs


The "documentation" word is used 8 times in this section.
Rephrase to avoid the unneeded repetition. For example:
We welcome contributions to the MFTF documentation, which is kept within the /docs/ folder in this repository.
This page describes the submitting process and serves as a template for a properly written content.
The contribution workflow is the same as submitting code.
The content in this repository is also a source for the [MFTF guide topics][].

I don't see the changes.

dshevtsov · 2019-04-16T18:55:54Z

.github/DOCUMENTATION_TEMPLATE.md

+We will inform you if it needs any additional processing.
+
+The documentation in this repository is used as the source for the [MFTF documentation][].
+Any changes to the Table of Contents will need to be made via a separate PR in the regular [Magento Developer documentation repository][].


Replace via with other word.

See DevDocs style guide:

Non-English words and weak phrases
Some non-English words and abbreviations are difficult to translate, and some users might be unfamiliar with them.

Avoid the following common words and phrases

Info
Etc. or etcetera
e.g.
Misc. or miscellaneous
Via
Make sure

It is not clear why Table of Contents is capitalized.

Replace PR with pull request. Avoid abbreviations. GitHub interface doesn't use this abbreviation, so it can be not clear (GitHub article About pull requests)

See DevDocs style guide:

Acronyms
Use only the most obvious acronyms. For instance, use PHP, HTML, XML for the names of those computer languages, not an unknown acronym. Try to avoid acronyms in your text when possible.

I don't see the changes.

dshevtsov

When I read the DOCUMENTATION_TEMPLETE topic, I don't see initial Markdown formatting.
Wrap examples in code blocks to show their implementation like:

```
your example
```

Refer to the DevDocs basic template for more examples.

.github/DOCUMENTATION_TEMPLATE.md

dshevtsov

Suggested minor changes

Co-Authored-By: Dmitry Shevtsov <[email protected]>

KevinBKozan and others added 4 commits January 29, 2019 09:31

Merge pull request magento#306 from magento/develop

2c8a4c3

MFTF 2.3.13 - Merge Develop to Master

Merge pull request magento#311 from magento/develop

b4002b3

MFTF 2.3.14 - Merge develop to master

Updating contribution guides for docs.

6c9c34d

Merge branch 'develop' into db_contributions

ef7a76e

okolesnyk requested review from dshevtsov and okolesnyk April 1, 2019 19:17

dshevtsov approved these changes Apr 1, 2019

View reviewed changes

dshevtsov suggested changes Apr 1, 2019

View reviewed changes

dobooth and others added 13 commits April 2, 2019 11:33

Merge branch 'develop' of github.com:magento/magento2-functional-test…

06d2e91

…ing-framework

Update .github/CONTRIBUTING.md

0c43a9e

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

5569b0a

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

2cc5666

Co-Authored-By: dobooth <[email protected]>

Fixes per review.

2290e2e

Update .github/DOCUMENTATION_TEMPLATE.md

a6786ee

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

a0faa1d

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

5f27f40

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

acc9238

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

978d945

Co-Authored-By: dobooth <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

6182ec9

Co-Authored-By: dobooth <[email protected]>

More review fixes.

447ed0f

Fixed link.

2099d30

dshevtsov reviewed Apr 2, 2019

View reviewed changes

.github/DOCUMENTATION_TEMPLATE.md Outdated Show resolved Hide resolved

Fixed header

9c68e7d

dshevtsov reviewed Apr 5, 2019

View reviewed changes

dobooth added 4 commits April 5, 2019 14:54

Merge branch 'master' into db_contributions

539a562

Fixes per review.

9501614

Cleaned up header

d0fd11b

Merge branch 'develop' into db_contributions

b9d2459

dshevtsov reviewed Apr 15, 2019

View reviewed changes

Grammar fix.

0b23734

dshevtsov suggested changes Apr 16, 2019

View reviewed changes

KevinBKozan added the DOC label Apr 24, 2019

Fixed grammar.

70e59a5

dobooth force-pushed the db_contributions branch from fdb9614 to 70e59a5 Compare April 24, 2019 16:57

dshevtsov suggested changes Apr 24, 2019

View reviewed changes

dobooth added 3 commits April 29, 2019 15:51

Indenting so markdown syntax shows.

2eef763

Indenting so markdown syntax shows.

42bc8d1

Linked to Basic Template.

51d66eb

dshevtsov reviewed May 21, 2019

View reviewed changes

.github/DOCUMENTATION_TEMPLATE.md Outdated Show resolved Hide resolved

dshevtsov reviewed May 21, 2019

View reviewed changes

.github/DOCUMENTATION_TEMPLATE.md Outdated Show resolved Hide resolved

dshevtsov suggested changes May 21, 2019

View reviewed changes

dobooth and others added 3 commits May 21, 2019 12:35

Update .github/DOCUMENTATION_TEMPLATE.md

8c7c139

Co-Authored-By: Dmitry Shevtsov <[email protected]>

Update .github/DOCUMENTATION_TEMPLATE.md

f03a564

Co-Authored-By: Dmitry Shevtsov <[email protected]>

Merge branch 'develop' into db_contributions

eaa1d0e

tomreece approved these changes May 21, 2019

View reviewed changes

tomreece merged commit 291bad3 into magento:develop May 21, 2019

dobooth deleted the db_contributions branch July 18, 2019 14:58

	For the documentation contribution guidelines, see [DOCUMENTATION_TEMPLATE][].
	For the documentation contribution guidelines, see [documentation template][].

	[DOCUMENTATION_TEMPLATE]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.html
	[DOCUMENTATION_TEMPLATE]: https://github.com/magento/devdocs/blob/master/.github/CONTRIBUTING.md

	Replace the `xml` with the file extension of the code sample type. Use `bash` for command-line text.
	Replace the `xml` with the corresponding language (tupe) of the code sample. Use `bash` for shell commands and `terminal` for terminal output.

	Markdown tables work for simple tables. If you need lists or other complex features within a cell, you may have to use a HTML table.
	Markdown formatting works for simple tables. It does not support multiline content within a cell, or split/merged cells within a row or column.

	- One empty line between content. No duplicate empty lines.
	- Do not duplicate blank lines.


		Any changes to the Table of Contents will need to be made in the regular [devdocs repo][].

		## Ordered lists - all heading have a blank line before and after, capitalize the first word only


		The contribution workflow for the Magento functional testing framework (MFTF) documentation is the same as submitting code.

		1. Create a branch from the `develop` branch in the [MFTF repo][].

Updating contribution guides for docs. #325

Updating contribution guides for docs. #325

Uh oh!

Conversation

dobooth commented Apr 1, 2019

Uh oh!

coveralls commented Apr 1, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dshevtsov Apr 2, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dshevtsov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dshevtsov Apr 15, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Apr 1, 2019 •

edited

Loading

dshevtsov Apr 2, 2019 •

edited

Loading

dshevtsov Apr 15, 2019 •

edited

Loading