[FLINK-12651][docs] Documentation Style Guide. #240

morsapaes · 2019-08-05T10:16:23Z

What is the purpose of the change

Proposing a documentation style guide to support and standardize new documentation contributions. This should also help in the long-haul effort of reworking existing documentation (FLIP-42). Feedback and suggestions are welcome!

TODO: there are already some improvement points mentioned in the draft document.

Brief change log

Adding a new section to the "How to Contribute" navigation sidebar and linking it from within "Contributing Documentation".

Verifying this change

This change is non-code related.

Does this pull request potentially affect one of the following parts:

Dependencies (does it add or upgrade a dependency): no
The public API, i.e., is any changed class annotated with @Public(Evolving): no
The serializers: no
The runtime per-record code paths (performance sensitive): no
Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Yarn/Mesos, ZooKeeper: no
The S3 file system connector: no

Documentation

Does this pull request introduce a new feature? no
If yes, how is the feature documented? not applicable

Sync with upstream repo.

Proposing a guide to support and standardize documentation contributions.

sjwiesman

Thanks for driving this @morsapaes. Overall I think the guide makes sense, the thing we have to add to the initial version is adding an Apache license to each file.

contributing/docs-style.md

… statement in every documentation file.

contributing/docs-style.md

Co-Authored-By: Robert Metzger <89049+rmetzger@users.noreply.github.com>

…ions. Also replaced the syntax of markdown highlights to get rid of the eye-stabbing red background color.

sjwiesman · 2019-12-09T16:51:34Z

@fhueske @rmetzger What's your opinion on the status of this style guide? Since we can expect a large influx of documentation PR's for 1.10 it might be a good time to merge this.

rmetzger

Thanks for addressing my comments. The change is good to merge.

fhueske · 2019-12-11T12:25:39Z

I'm having a look right now.

fhueske

Thanks for this great documentation guide @morsapaes!
I left a few comments and suggestions.

Best, Fabian

fhueske · 2019-12-11T12:22:13Z

contributing/docs-style.md

+
+Below, you find some basic guidelines that can help ensure readability and accessibility in your writing. For a deeper and more complete dive into language style, also refer to the [General Guiding Principles](#general-guiding-principles).
+
+### Addressing the User


Concrete examples would be good for the points listed here.

Of the following four points, only two are about addressing the user. Can you generalize the heading?

fhueske · 2019-12-11T12:22:36Z

contributing/docs-style.md

+
+### Addressing the User
+
+* **Use active voice.** [Active voice](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498) supports brevity and makes content more engaging. If you add _by squirrels_ after the verb in a sentence and it still makes sense, you are using the passive voice.


I didn't really get the last sentence. An example would help.

fhueske · 2019-12-11T12:27:11Z

contributing/docs-style.md

+* **Avoid qualifying and prejudging actions.** For a user that is frustrated or struggling to complete an action, using words like _quick_ or _easy_ can lead to a poor documentation experience.
+
+### Using Flink-specific Terms
+Use clear definitions of terms or provide additional instructions on what something means by adding a link to a helpful resource, such as other documentation pages or the [Flink Glossary](https://ci.apache.org/projects/flink/flink-docs-master/concepts/glossary.html).


Add a note that it would be good to propose new terms for the Glossary?

fhueske · 2019-12-11T14:53:36Z

contributing/docs-style.md

+In the documentation build, navigation is defined using properties configured in the front-matter variables of each page.
+
+<font size="3">
+<table width="100%" class="table table-bordered">


Combine this table with the other table about variables in the header? Not sure if it is clear that these variables can/should be set in the page header.

fhueske · 2019-12-11T14:56:09Z

contributing/docs-style.md

+
+* To highlight a tip or piece of information that may be helpful to know:
+
+  ```liquid


add an info text and a closing "tag" to show how it is used in practice

There is no closing tag for this syntax.

fhueske · 2019-12-11T14:56:25Z

contributing/docs-style.md

+* To signal danger of pitfalls or call attention to an important piece of information that is crucial to follow:
+
+  ```liquid
+  {{ "{% warn " }}%}


add an warning text and a closing "tag" to show how it is used in practice

fhueske · 2019-12-11T14:58:30Z

contributing/docs-style.md

+
+Adding links to documentation is an effective way to guide the user into a better understanding of the topic being discussed without the risk of overwriting.
+
+* **Links between sections in the page.** Each heading generates an implicit identifier to directly link it within a page. This identifier is generated by making the heading lowercase and replacing internal spaces with hyphens.


Links between -> Links to

fhueske · 2019-12-11T14:59:18Z

contributing/docs-style.md

+  [Link Text](#heading-title) 
+  ```
+
+* **Links between files in the repository.** The base relative path to the domain of the documentation is available as a configuration variable named `baseurl`.


Links to other pages of the Flink documentation?

fhueske · 2019-12-11T14:59:32Z

contributing/docs-style.md

+  [Link Text]({{ "{{ site.baseurl " }}}}/path/to/link_page.html)
+  ```
+
+* **External links**


Links to external pages?

fhueske · 2019-12-11T15:08:07Z

contributing/docs-style.md

+  ```html
+  <div class="codetabs" markdown="1">
+
+  <div data-lang="java" markdown="1"> … </div>


expand example and show that syntax highlighting needs to be enabled here as well:

<div class="codetabs" markdown="1"> <div data-lang="java" markdown="1"> {% highlight java%} // Java Code {% endhighlight%} </div> <div data-lang="scala" markdown="1"> {% highlight scala%} // Scala Code {% endhighlight%} </div> </div>

aljoscha · 2020-02-05T13:03:33Z

contributing/docs-style.md

+In the documentation build, the **Table Of Contents** (TOC) is automatically generated from the headings of the page using the following line of markup:
+
+```liquid
+{{ "{% toc " }}%}


This is interesting, the Flink website uses {% toc %} while the Flink Documentation uses {:toc}, for the doc we should probably stick to {:toc} then.

aljoscha · 2020-02-05T13:06:43Z

contributing/docs-style.md

+
+* To highlight a tip or piece of information that may be helpful to know:
+
+  ```liquid


There is no closing tag for this syntax.

aljoscha · 2020-02-05T13:09:24Z

contributing/docs-style.md

+  It's recommended to use Back to Top links at least at the end of each Level-2 section.
+</div>
+
+### Annotations


This means we want to move away completely from the block-style highlight blocks that are used, for example, in https://ci.apache.org/projects/flink/flink-docs-master/dev/stream/state/broadcast_state.html?

aljoscha · 2020-02-05T13:12:04Z

contributing/docs-style.md

+
+* **Use active voice.** [Active voice](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498) supports brevity and makes content more engaging. If you add _by squirrels_ after the verb in a sentence and it still makes sense, you are using the passive voice.
+
+* **Use you, never we.** Using _we_ can be confusing and patronizing to some users, giving the impression that “we are all members of a secret club and _you_ didn’t get a membership invite”. Address the user as _you_.


Do we have a rough estimate of how much of the documentation is written using you vs more passive constructions?

The docs are all over the place but I've been pushing this pretty hard in my reviews the past few months.

morsapaes · 2020-02-07T11:13:34Z

The original fork is gone, so I'll just close this PR and open a new one, already incorporating all your suggested changes.

See you on the other side.

morsapaes added 2 commits July 24, 2019 00:29

Merge pull request #1 from apache/asf-site

b65d99c

Sync with upstream repo.

[FLINK-12651] Documentation Style Guide.

03d7723

Proposing a guide to support and standardize documentation contributions.

sjwiesman requested changes Aug 5, 2019

View reviewed changes

contributing/docs-style.md Show resolved Hide resolved

Adding in the guideline regarding the inclusion of the Apache License…

95f4fbb

… statement in every documentation file.

rmetzger reviewed Aug 7, 2019

View reviewed changes

contributing/docs-style.md Outdated Show resolved Hide resolved

rmetzger reviewed Aug 7, 2019

View reviewed changes

contributing/docs-style.md Outdated Show resolved Hide resolved

rmetzger reviewed Aug 7, 2019

View reviewed changes

contributing/docs-style.md Outdated Show resolved Hide resolved

morsapaes and others added 2 commits August 16, 2019 16:21

Update contributing/docs-style.md

b6cbcff

Co-Authored-By: Robert Metzger <89049+rmetzger@users.noreply.github.com>

Twitched the general principles section according to Robert's suggest…

9bf5215

…ions. Also replaced the syntax of markdown highlights to get rid of the eye-stabbing red background color.

rmetzger approved these changes Dec 10, 2019

View reviewed changes

fhueske reviewed Dec 11, 2019

View reviewed changes

aljoscha reviewed Feb 5, 2020

View reviewed changes

morsapaes closed this Feb 7, 2020

morsapaes mentioned this pull request Feb 7, 2020

[FLINK-12651] Adding a Documentation Style Guide. #303

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[FLINK-12651][docs] Documentation Style Guide. #240

[FLINK-12651][docs] Documentation Style Guide. #240

morsapaes commented Aug 5, 2019

sjwiesman left a comment

sjwiesman commented Dec 9, 2019

rmetzger left a comment

fhueske commented Dec 11, 2019

fhueske left a comment

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

aljoscha Feb 5, 2020

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

fhueske Dec 11, 2019

aljoscha Feb 5, 2020

aljoscha Feb 5, 2020

aljoscha Feb 5, 2020

aljoscha Feb 5, 2020

sjwiesman Feb 5, 2020

morsapaes commented Feb 7, 2020


		Below, you find some basic guidelines that can help ensure readability and accessibility in your writing. For a deeper and more complete dive into language style, also refer to the [General Guiding Principles](#general-guiding-principles).

		### Addressing the User


		### Addressing the User

		* Use active voice. [Active voice](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498) supports brevity and makes content more engaging. If you add _by squirrels_ after the verb in a sentence and it still makes sense, you are using the passive voice.


		* To highlight a tip or piece of information that may be helpful to know:

		```liquid


		Adding links to documentation is an effective way to guide the user into a better understanding of the topic being discussed without the risk of overwriting.

		* Links between sections in the page. Each heading generates an implicit identifier to directly link it within a page. This identifier is generated by making the heading lowercase and replacing internal spaces with hyphens.


		* Use active voice. [Active voice](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498) supports brevity and makes content more engaging. If you add _by squirrels_ after the verb in a sentence and it still makes sense, you are using the passive voice.

		* Use you, never we. Using _we_ can be confusing and patronizing to some users, giving the impression that “we are all members of a secret club and _you_ didn’t get a membership invite”. Address the user as _you_.

[FLINK-12651][docs] Documentation Style Guide. #240

[FLINK-12651][docs] Documentation Style Guide. #240

Conversation

morsapaes commented Aug 5, 2019

What is the purpose of the change

Brief change log

Verifying this change

Does this pull request potentially affect one of the following parts:

Documentation

sjwiesman left a comment

Choose a reason for hiding this comment

sjwiesman commented Dec 9, 2019

rmetzger left a comment

Choose a reason for hiding this comment

fhueske commented Dec 11, 2019

fhueske left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

morsapaes commented Feb 7, 2020