Asciidoc and Markdown style guides?

[erget]

It would be nice to have a style guide for the documents that we take care of. Perhaps a topic for the upcoming user meeting and even a hackathon? 🤔 I'll contribute if anybody else thinks this is a good idea.

As proposed in cf-convention/discuss#152 (comment)

[davidhassell]

Great idea. Lets add that to teh existing scheduled hackathon: cf-convention/discuss#152 (comment)

[sadielbartholomew]

I also agree, this could be very useful. Though I would recommend that we refer to an existing guide/standard, rather than writing our own (that may have been the intention anyway, not sure!). I am thinking a clear and concise (enough) page of style guidance such as the Google style guides, e.g. here for Markdown (though they don't seem to have anything covering Asciidoc), would work well. And to cater for specific rules we want for the CF case, e.g:

Putting each sentence on a single line would help get us there

we could emphasise our own items of guidance, such as this one, and otherwise say something like "and for general style please refer to and abide by <existing style guide>".

And if there are auto-formatting tools available that we can utilise, even better, though I have not head of one for Markdown, at least. We can do a survey to see if anything exists, of course.

[erget]

For Asciidoc in #381 @dnowacki-usgs found this which at first blush looks good to me.

[erget]

After agreeing on one we might need a separate task to implement it to start.

One element I could imagine is taking a look at the use of monotype - in 5.6.1 I just noticed that we have some places where attributes are in normal type, rather than monotype, and we'd likely improve readability by changing that.

[erget]

Same in following chapters, e.g. In chapter 6 you've got some naked URLs.

[erget]

And "fixed_angle_axis" in table F.1 has formatting issues - it's bolded, not monotyped.

[erget]

Same thing with sweep_angle_axis...

[erget]

H.3 - in the caption of the example we'd benefit from some monotyping.

[erget]

Consistent number of linebreaks between paragraphs?

[erget]

Eliminate trailing whitespace?

[jesusff]

The lack of monotypes at some places is due to a trailing space right before the ending mark.

Does it make sense to also try to stick to a single way of writing bold and monotype together? There is currently a mix of

**`bold monotype`**

and

`**bold monotype**`

A single way would ease automatic location of errors such as extra space.

[erget]

Yes, I think that would make sense. How do you like the style guides posted above?

[davidhassell]

I've had a brief look at both style guides, and they look fine to me. Thanks.

[jesusff]

Yes, they look good. There are some TODO parts, though. E.g. here there is no decision on monotype:

https://asciidoctor.org/docs/asciidoc-recommended-practices/#literal-text

but I think for this specific matter we clearly went for backticks to represent them. There is no plus sign representation for monotypes in the whole document.