Is making grammatical and spelling changes to shared documents and code bad etiquette?

Question

I work in a small development company which has an open and friendly atmosphere, and am the most junior employee. We have a cloud-based repository for user documentation, private documents such as server specifications and developer deployment guides. Many of these are written with haste or aren't proof read, and often when I read through the documents for my work tasks I come across simple spelling mistakes, typos and incorrect grammar. In other instances, in the code I come across many typos in debug statements, console output and messages that are presented to the user.

Would it be considered bad etiquette, or petty if:

• I edited these documents to fix grammar and spelling, especially on the documents which aren't public-facing?
• The original author is dyslexic?
• I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Answer 1

I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Tread carefully here.

Often, any code changes have down-stream effects. A code review might be required. Testing might be required. A security review might be required. Etc. Changing spelling and grammar mistakes might trigger a lot of unscheduled work from others.

And while your intent is to make no changes to the actual functionality, bugs happen.

Before you change any code - ask.

Would it be considered bad etiquette, or petty if:

• I edited these documents to fix grammar and spelling, especially on the documents which aren't public-facing?
• The original author is dyslexic?

That depends mostly on the culture of your organization.

In some companies, continuous change by everyone who reads such documents is welcome. In other companies, it would be considered rude without the author's permission.

Answer 2

I consider this kind of change an improvement in quality. Internal documentation has a value although it's not facing end-user, and improving the quality of it makes it more valuable. I also personally tend to trust documentation more if it doesn't have a huge amount of typos in it. Sometimes a typo or wrong grammar might also change the meaning or lead to misunderstandings.

To summarize it: I find it rather positive.

Be careful though that if you happen to spend a lot of time doing that, people might wonder if you don't have anything better to do, like coding...

Answer 3

Assume the worst of your changes:

• You make mistakes that breaks something
• Your relatively minor commits might clutter changelogs etc
• Your employer might think your time is spent doing more useful things

Due to this, I only make "unsolicited" changes if, basically, I was changing the code/document anyway. So if I'm being tasked changing some class, and I know that its functionality will have to be re-tested anyway, I might as well also refactor it and fix some spelling it if I genuinely believe it will improve quality or save everyone time in the end. As other answer mentioned: the "boy scout rule" - leave the camp site more tidy than they were when you got there.

But, don't accidentally start bush fires by camping unnecessarily :) For any other changes, make a case of it to whoever is deciding what you do. Explain benefits of the fixes, and any risks. Examples of benefits could be that misspelled code inhibits searching the code base, negative user perception from misspelled messages or documents, etc. Let them decide whether its worth the time/risk.

Answer 4

I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Are there any mistake visible for the public (in front-end) or the client (at client's console log)?

If yes, ask the team/project leader about authorizing you to correct them.

If no, do nothing or ask the team/project leader if you can do some refactor and fix then with any other issues the code could have.

In any case, don't criticize your coworker, specially if he's dyslexic.

Answer 5

If we are talking really minor changes such as fixing typos or missing commas etc. then I wouldn't say it's a bad thing to just fix them as you find them. What I wouldn't do is go around telling anyone you've made the changes as that might seem like attention-seeking at best and being a petty spelling/grammar-nazi at worst.

Another advantage to fix-as-you-find is that you don't want to come off as someone who is hunting for these mistakes.

Code can be a little different - although you do state that you aren't changing actual code so I'm assuming it is just things like comments so there is zero possiblity of it impacting on functionality in which case I'd suggest that's fine.

Answer 6

Do not change code unless it is tied directly to the bug or enhancement ticket you are working on. (you do have a ticketing system of some sort for work on existing systems, right?) Your change should also be necessary to complete the work of the ticket.

If you firmly believe that this code should be changed, create a ticket for review and if approved, you can do the work.

As the saying goes, "No good deed goes unpunished". There are so many ways that what seems like a trivial edit could go wrong, sometimes in a delayed fashion.

For example, at my company we have built an alert system based on monitoring/scraping log files. Error messages in logs can generate anything from a minor warning to an all hands alert. Over the years, we have unfortunately created log error messages with all variation of typos. If some over-zealous developer "fixed" the error messages, our alerting system might suddenly go silent.

Answer 7

What this really boils down to is the context.

For instance, I work for a multi-national company on a team that is located across multiple countries. I'm the sole native English speaker, so I encounter grammar and spelling mistakes in our code names and comments on a daily basis.

I typically leave them as are, as correcting the mistakes yields no benefit, and it is always very easy to understand the intention of the writer due to the context. (Off the top of my head, I can think of a folder accessed by several files with the name "ressources".

Changing names can have waterfall effects if it's an actual code object, and if the name is descriptive albeit misspelled, I don't see the benefit to adding to your own workload.

I don't believe my foreign coworkers would be offended if I started correcting their errors in my commits, but over time, if I were to do it over and over and over again, they may start to feel like I think their English skills are inadequate.

Bottom line, ask yourself if the context of the situation is worth the extra work and if the context means a potential slight against the original author.

I don't believe that correcting spelling and grammar mistakes in other's code will give anyone the impression that you're a better coder for it, only that you have a better grasp on the English language.

Answer 8

Public facing documents and log entries should have much higher standard in terms of spelling and grammar correctness than internal documents and code. Of course, it is advisable as well to constantly clean up the code you are working on. This means that whenever you are working on a feature/bugfix, you should leave the affected part cleaner than it was before (boyscout rule). What should not be the case is that when you edit the code, the changes contain only fixes of grammar and spelling.

Also, you should ask your manager before doing this habit regularly, because he/she can help you in approaching your colleagues that could be sensitive towards correcting their contributions.

Answer 9

There are two categories you are dealing with here: public facing documents and internal documents and code.

For internal documents and code, don't bother with superfluous changes. As long as the files are understandable and work as they should, then there's not really anything to be gained. Edits like this don't really add anything and can clutter up your version control history. However, if you are already making a change to a particular document and see some typos to fix too, then go ahead. In that case it's really more of an add-on to an already necessary change.

For public facing documents and UI messages, it is important to make sure there are few errors and everything is grammatically correct. If it's something that is clearly incorrect, then I would certainly change it. If it is a more subjective change (e.g. changing wording, or the Oxford comma), then I would consult with the primary author or your manager before saving any edits. Again, I find a lot of small edits like this can clutter up version control, so I personally prefer to save the changes with other more important updates or to set aside the edits and do a batch upload of a bunch of copy-edits at once. That's something you can talk to your manager about to see what they prefer.

Answer 10

I work in a small development company which has an open and friendly atmosphere, and am the most junior employee.

You have a manager. That is the person you should be asking !

Our opinions can be looked on as advice, but your boss is the person who must make a decision. They must decide how your time is best used.

I come across simple spelling mistakes, typos and incorrect grammar.

If you are authorized to change these documents and certain you are not changing the intended meaning, then I presume it's OK. However, being certain of the intended meaning is non-trivial and it's easy to alter the meaning without intending to.

In other instances, in the code I come across many typos in debug statements, console output and messages that are presented to the user.

Errors in code (messages of any kind included) need to be properly addressed using a bug tracking system. They can then be prioritized properly and dealt with on that basis.

And it's possible to screw up these changes and mess up code doing it. Happens all the time.

Would it be considered bad etiquette, or petty if:

I edited these documents to fix grammar and spelling, especially on the documents which aren't public-facing?

Private internal documents do not particularly need to be fixed in this way. Prioritize other work over this.

The original author is dyslexic ?

The original author's capabilities or limitations are not relevant to how your time is used.

I were to commit fixes to spelling and grammar mistakes in code, and make no changes to the actual functionality of the code?

Any change to code is a formal change. Changes to comments and other elements can introduce bugs - people make mistakes doing this. I advise against this without explicit instruction from your line management.

Answer 11

If the document isn't public-facing, as you mentioned for some of them, then what is the actual benefit to making these corrections, other than it not bothering you?

If you're not changing the functionality of the code, and the improved grammatical presentation does not impact the company's image, at all, then you have added no value to the code.

If you spend time "fixing" something that adds no value, you have just wasted your own time and your employer's time and money, which is not the way to go for anyone, but especially the most junior person in the food chain.

You're likely to irritate people, who will ask "why did this need fixing?", and you're likely to raise the general question - "Doesn't this person have value-adding work to do? If not, is this person's job necessary for us to have, at all?"

Do not even ask if it's okay to make these fixes, because there is no problem to fix, and no improvement offered by making the fix.

For messages that do get presented to end-users/customers, definitely ID them for fixing, let someone higher up know that you saw it, and offer to correct it. Certainly, basic errors of that sort do not reflect well on the company, so fixing those does add substantial value.