Documentation Linter

Documentation Linter

[Mark Van De Vyver]

[-- Attachment #1: Type: text/plain, Size: 1179 bytes --]

Hi,
As mentioned in my previous message - which hasn't shown up yet - I'm new to Yocto and thought to try contribute via the docs.
I've made my comment on the conversion from DocBook, and this proposal will be impacted by that effort - hopefully a part of the conversion, and in a way that does not block or interfere.

The idea I had was to introduce a prose linting tool.  Specifically, [Vale](https://errata-ai.gitbook.io/vale/).

Before going into the details, lets first establish if any of the following would be of use/value?

It would allow the project to achieve some consistency across paragraphs/pages/documents/repositories.
This would become more important if the project decided to exploit [Antora's](https://antora.org) ability to create a document from different repositories.
In such a case a repo could ensure its documentation had a closer 'fit' within the wider project documentation by ensuring it passed the same lint settings.
After the inital run/port is complete the documentation lint step could be added to the githooks that verify any new commit is green.

Thoughts?
--
Kind regards
Mark

Mark Van de Vyver, B.Bus(Hons), PhD(Dist)

[-- Attachment #2: Type: text/html, Size: 1296 bytes --]

Re: [docs] Documentation Linter

[Khem Raj]

On 5/27/20 9:00 PM, Mark Van De Vyver wrote:
> Hi,
> As mentioned in my previous message - which hasn't shown up yet - I'm 
> new to Yocto and thought to try contribute via the docs.
> I've made my comment on the conversion from DocBook, and this proposal 
> will be impacted by that effort - hopefully a part of the conversion, 
> and in a way that does not block or interfere.
> 
> The idea I had was to introduce a prose linting tool.  Specifically, 
> [Vale](https://errata-ai.gitbook.io/vale/).
> 
> Before going into the details, lets first establish if any of the 
> following would be of use/value?
> 
> It would allow the project to achieve some consistency across 
> paragraphs/pages/documents/repositories.
> This would become more important if the project decided to exploit 
> [Antora's](https://antora.org) ability to create a document from 
> different repositories.
> In such a case a repo could ensure its documentation had a closer 'fit' 
> within the wider project documentation by ensuring it passed the same 
> lint settings.
> After the inital run/port is complete the documentation lint step could 
> be added to the githooks that verify any new commit is green.
> 
> Thoughts?

I really like the idea of linter.

> -- 
> Kind regards
> Mark
> Mark Van de Vyver, B.Bus(Hons), PhD(Dist)
> 
> 
>