Document Style Guide Needed

[benev0]

Why Documentation Is Better With a Style Guide

Disambiguate Multiple Solutions

Presently, all documents may be reviewed at will by the community. This is not an issue. However, as a result of the lack of style guide and varying opinions of reviewers, the reviews are only based off of opinion. These solely opinion reviews are difficult to accept even when addressing issues with pull requests, as there are no hard or soft correctness rules.

The crux of the issue is any solution posed in a review has an equally valid alternative and any problem raised has multiple solutions. To prevent unneeded delays caused by selecting valid solutions a style guide is required.

#358 is one of the latest closures that can be attributed to style confusions.

Improve the Reading Experience

Access to the content can be improved. Consistent document formatting and vocabulary reduces the time that a reader needs to comprehend said document.

Reduce Required Writing Level

Removing or reducing the stylistic variable will improve the ability of early and non-native English writers. A well written style guide outlines what is required of a writer. If a writer follows a formula to crate a stylistically correct document, then the writer is only concerned with the content of their work rather than focusing on superfluous details.

Allow for Revision

The current state of documentation will be improved. Without a style guide readers can tell that documents have issues, but cannot pinpoint how these issue should be solved. When a style guide is applied to old work both the issues with the work and the solution to that work will be clear.

Revisions based only off of opinion will become less common. Once a document no longer contradicts the style guide there is little reason to edit it.

What Is Required?

This will need to be up to the community, but should address several key points not limited to the ones below. Ideally one canonical solution can be selected per point.

1. Perspective
   a single style from one perspective
2. Syntax
   allowed, encouraged, prohibited, required
3. Vocabulary
   allowed, encouraged, prohibited, required
4. Formatting
   markdown (indent tab space etc.)
   document (which sections to include in what order)
   each with allowed, encouraged, prohibited, required
5. Figures
   charts, diagrams, images, embedded content
   each with allowed, encouraged, prohibited, required
6. Links
   internal, external
   each with allowed, encouraged, prohibited, required
7. Citations
   allowed, encouraged, prohibited, required

[Partmedia]

Thanks for reporting. I agree documentation is better with a style guide, but at the same time we're in the business of getting things documented and not necessarily producing high prose.

As the maintainer likely most guilty of grammar policing, I do want to flag issues in docs before they're committed. Sometimes there are submissions with glaring spelling and grammar mistakes. Sometimes, docs are written like chatroom comments and lack professionalism that you'd expect from reading documentation.

This chapter on writing in a technical communication style summarizes my opinions about style for our documentation. It should answer most of your "Required" bullets.

[benev0]

... at the same time we're in the business of getting things documented and not necessarily producing high prose.

I agree, and I see that my rhetoric is pushing for an excessive standard. Ultimately I would like to see a democratization of documentation with standards within reach of any writer.

This chapter on writing in a technical communication style summarizes my opinions about style for our documentation. It should answer most of your "Required" bullets.

I do believe that all the elements should be addressed; however, perhaps not as extensively as implied by "allowed, encouraged, prohibited, required." Selecting a quality standard such as the book linked and supplementing it with a small set of concrete addendums to said standard is both a fast and effective way to create standards.

[benev0]

The following some anecdotal concern that I have with using published text. Linking or deferring to to an external text, in my observation of peers, tends to discourage readers who are not already comfortable with the topic. That is, although the linked resource is written so that little prior know how required, I am concerned that using a text that portrays itself as university level will result in reading being discouraged. As it is not efficient to remake the text I still recommend linking to it.

Points 1-3 should be addressed nearly fully externally. The remaining points will likely need at least some arbitrary decisions made so should be addressed directly.

Here are some notes:
4: Markdown formatting is the only point which can have a completely concrete standard if addressed with a linter.

5: Citation of discord messages, files on github, and externally hosted images should be addressed in full as it creates future issues.

5: Versioning code samples should be addressed.

[Partmedia]

Linking or deferring to to an external text, in my observation of peers, tends to discourage readers who are not already comfortable with the topic.

If someone isn't already going to read, there's no sense in re-writing it ourselves to have it doubly not read. The linked text is (1) already written and (2) likely better than whatever we might independently come up with.

I can already see something that we come up with to be excessively didactic, verbose, and confusing.

I am concerned that using a text that portrays itself as university level...

Just because it is published by the Ohio State University Press, does not mean that the intended audience is university-level. University presses can and do publish for a variety of audiences. The linked text seems concise, easy to read, and provides many examples.

4: Markdown formatting is the only point which can have a completely concrete standard if addressed with a linter.

I feel that as long as mdbook understand it, it's acceptable.

5: Citation of discord messages, files on github, and externally hosted images should be addressed in full as it creates future issues.

I agree.

5: Versioning code samples should be addressed.

What do you mean here?

[benev0]

...

If someone isn't already going to read, there's no sense in re-writing it ourselves to have it doubly not read. The linked text is (1) already written and (2) likely better than whatever we might independently come up with.

I can already see something that we come up with to be excessively didactic, verbose, and confusing.

...

Just because it is published by the Ohio State University Press, does not mean that the intended audience is university-level. University presses can and do publish for a variety of audiences. The linked text seems concise, easy to read, and provides many examples.

I agree on all points here. What I am expecting to be relevant is not the actual level of the text but the title and publisher; regardless, it should be expected that there will be some submissions which clearly do not meet standard. I see now that it is not clear from what I communicated. My real concern is how such submissions are reviewed. Some guidelines to avoid devolving into RTFM should be set.

I feel that as long as mdbook understand it, it's acceptable.

As a bare minimum, but to improve editing it is my opinion that the plain text be formatted alike, so that for the editor reading the plan text is not burdensome. A linter is one option to encourage such a standard.

5: Versioning code samples should be addressed.

What do you mean here?

RobustToolbox (RT) moves around quite a bit including the obsoleting of methods. Code samples which can included an RT version should include one.

[Partmedia]

My real concern is how such submissions are reviewed. Some guidelines to avoid devolving into RTFM should be set.

Not sure what the best approach is here. Some reviewers correct minor nitpicks themselves, others prefer the submitter to make all changes including nitpicks. Reviewers try to be helpful but can't explain every concept every time. "Reword with active voice" and linking the manual is probably the best we can reasonably do. "How to be helpful in a review" is sort of out of scope for a style guide, which is what this issue is about.

[Partmedia]

I started "Style" and "Review" sections on the Guide to Editing Docs. Comments and concerns are welcome here.

[benev0]

I started "Style" and "Review" sections on the Guide to Editing Docs. Comments and concerns are welcome here.

thank you

see change here