Line length in docs

[Alex Rukletsov <al...@mesosphere.com>]

What do folks think about introducing a limit for line length in docs?
First off, here are my thoughts against the limit:
  * We should be careful about introducing more hurdles, especially for
docs. We want people, also contributors outside the community, to improve
documentation; hence we should make the process easier, or at least not
more complicated.
  * People usually render docs locally in a markdown application, that's
why line length is not that crucial like comments length.

However, I often find myself reading and updating docs from the same editor
I read and write code. In this case, 700+ lines become annoying, see e.g.
[1].

My proposal is:
  * have an agreement among committers, i.e. put it into "committing.md",
that lines in docs are generally limited to 80 chars;
  * refrain from putting this limit in both "markdown-style-guide.md" and
"c++-style-guide.md";
  * sweep-update all existing docs so contributors can follow the pattern.

[1]
https://github.com/apache/mesos/blob/a138e2246a30c4b5c9bc3f7069ad12204dcaffbc/docs/architecture.md

Re: Line length in docs

[Alexander Rojas <al...@mesosphere.io>]

+1 (Actually more like +10)

But I think your reasons are not the main problem in solving this issue. For me, when we have whole paragraphs in one line, and I want to see the changes in the document, even adding a comma renders the whole paragraph as changed, which makes the tracking of changes extremely painful.

> On 05 May 2016, at 15:29, Alex Rukletsov <al...@mesosphere.com> wrote:
> 
> What do folks think about introducing a limit for line length in docs?
> First off, here are my thoughts against the limit:
>  * We should be careful about introducing more hurdles, especially for
> docs. We want people, also contributors outside the community, to improve
> documentation; hence we should make the process easier, or at least not
> more complicated.
>  * People usually render docs locally in a markdown application, that's
> why line length is not that crucial like comments length.
> 
> However, I often find myself reading and updating docs from the same editor
> I read and write code. In this case, 700+ lines become annoying, see e.g.
> [1].
> 
> My proposal is:
>  * have an agreement among committers, i.e. put it into "committing.md",
> that lines in docs are generally limited to 80 chars;
>  * refrain from putting this limit in both "markdown-style-guide.md" and
> "c++-style-guide.md";
>  * sweep-update all existing docs so contributors can follow the pattern.
> 
> [1]
> https://github.com/apache/mesos/blob/a138e2246a30c4b5c9bc3f7069ad12204dcaffbc/docs/architecture.md

Re: Line length in docs

[haosdent <ha...@gmail.com>]

+1.

>have an agreement among committers
It would better that we use a tool like cpplint.py to check this. It's a
bit hard to check whether the line overflow or not in reviewboard.

On Thu, May 5, 2016 at 9:29 PM, Alex Rukletsov <al...@mesosphere.com> wrote:

> What do folks think about introducing a limit for line length in docs?
> First off, here are my thoughts against the limit:
>   * We should be careful about introducing more hurdles, especially for
> docs. We want people, also contributors outside the community, to improve
> documentation; hence we should make the process easier, or at least not
> more complicated.
>   * People usually render docs locally in a markdown application, that's
> why line length is not that crucial like comments length.
>
> However, I often find myself reading and updating docs from the same editor
> I read and write code. In this case, 700+ lines become annoying, see e.g.
> [1].
>
> My proposal is:
>   * have an agreement among committers, i.e. put it into "committing.md",
> that lines in docs are generally limited to 80 chars;
>   * refrain from putting this limit in both "markdown-style-guide.md" and
> "c++-style-guide.md";
>   * sweep-update all existing docs so contributors can follow the pattern.
>
> [1]
>
> https://github.com/apache/mesos/blob/a138e2246a30c4b5c9bc3f7069ad12204dcaffbc/docs/architecture.md
>



-- 
Best Regards,
Haosdent Huang