armleo
commented
2 years ago Use active voice - e.g Do this as opposed to this should be done. Avoid saying "Let's" , Commands that are differentiated by font need not be explained as Type etc. Done.
Create a standard for instructions, commands, Notes, Warnings, Error Messages- These should be differentiated using proper markdown demarcations such as spaces, Indentations etc.
I am not sure if I did this correctly. Please take a look and provide feedback if I did make
Keep trademarks consistent
Done.
Refer to this section for Grammar and Abbreviations etc we did for OpenROAD for examples" https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/docs/contrib/Logger.md
Use simple, short sentences
I tried to follow it. If I missed some, please point out, so I can fix it.
This type of messaging should not be Done.
Please take a look at the current variant and let me know if it's not the way you wanted it.
Mandatory steps should not be a warning. They should have their own special notifier not to be confused with Warnings.
Done. Used Important
Spellcheck, spellcheck... Please!
Done.
dralabeing
Please pay attention to the following writing styles for consistency, brevity.
Use active voice - e.g Do this as opposed to this should be done. Avoid saying "Let's" , Commands that are differentiated by font need not be explained as Type etc.
Create a standard for instructions, commands, Notes, Warnings, Error Messages- These should be differentiated using proper markdown demarcations such as spaces, Indentations etc. (@Vitor Can give a quick Tutorial)
Refer to this section for Grammar and Abbreviations etc we did for OpenROAD for examples" https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/docs/contrib/Logger.md
Keep trademarks consistent OpenLANE → OpenLane OpenRoad →OpenROAD Mac OS X → macOS MAGIC → Magic
Use simple, short sentences For e.g This sentence "After installing all of the above, you need to make Docker available without sudo command in Step 2 and follow rest of the steps." should be wriiten as:
After you install <the specific thing, not the above enable docker without sudo as shown in. Proceed to
This type of messaging should not be Done The steps below might be simply outdated, OpenLane team encourages to follow the link to the official Docker documentatation Instead Check here for latest instructions for build. Do not refer to the OpenLane team and encouragement. Be specific about what instruction or warning you wish to convey e,g Refer to for
Mandatory steps should not be a warning. They should have their own special notifier not to be confused with Warnings.
Example,REBOOT! This is mandatory step. Without rebooting the user groups will no apply. DO NOT SKIP!
Replace Warning! with Important!
Spellcheck, spellcheck... Please!