angular/angular.io

docs(reactive-forms) Avoid bootstrap in template examples

peterkelly opened this issue · 4 comments

peterkelly commented

I've just been reading the Reactive Forms page on angular.io and there's a number of paragraphs like this:

Reminder: Ignore the many mentions of form-group, form-control, center-block, and checkbox in this markup. Those are bootstrap CSS classes that Angular itself ignores. Pay attention to the formGroupName and formControlName attributes. They are the Angular directives that bind the HTML controls to the Angular FormGroup and FormControl properties in the component class.

I'd like to suggest avoiding the use of bootstrap, or for that matter any CSS styling, when giving examples of templates — particularly when the class names used are similar to identifiers used for Angular modules/directives/classes etc. This would avoid both any potential confusion and the need to constantly remind people to ignore certain parts of the example code.

Foxandxss commented

Can you take a peek @kapunahelewong ?

kapunahelewong commented

@peterkelly thank you for the feedback. I wish those class names were different too. However, since the code samples come directly from the live examples, if we removed them, the live examples would be completely unstyled and hard to use. Though there are other CSS options, Bootstrap, as one of the most common, at least offers familiarity to many devs. If we created custom CSS, visitors would still have to sort out our custom class names. You make a solid point, though, and going forward, we'll definitely keep this in mind (seriously). Thanks again!

Deleted user commented

[issue.process]

@kapunahelewong The OP is 100% correct. The cognitive overhead is simply far too high.

we'll definitely keep this in mind (seriously)

I see that the project here closes tens of issues with similar comments ("will keep in mind" "will ensure" etc.). How to you track this? Even if you are memory-geniouses, how should someone who wants to follow development track this?

This is not the way to go.

Foxandxss commented

We have an internal document where we document everything that needs to be done.