Skip to content

Conversation

@fw-bot
Copy link
Collaborator

@fw-bot fw-bot commented Oct 25, 2022

Overview

This is a batch cherry pick of PR’s #2002, #1984, #1900, #1876, #1870, #1854, and #1824
I took the changes originally proposed in these PR’s and stacked them here on a fresh 15.0 base since they were all merge requests into 15.0.

Formatting updates

On top of the original changes proposed by @thomasdeleval, I went ahead and updated technicals for each affected RST file + associated images. Those changes are as follows in order to bring each doc up to standards:

  • fixed 100th character line breaks
  • added alt text to images with proper grammar
  • fixed indentations on RST tags
  • renamed images attached to respective RST files (when appropriate) to match new convention (usage_01.png —> uom-handling-vs-purchase.png), and updated RST links accordingly.
  • fixed some broken links + misnamed folders

Follow up items for review

I did not change any of the content other than what what the PRs originally suggested, however I think there are a number of improvements to be made around wording, grammar, and specificity of language.

Generally speaking, please consider the following suggestions in content review stage:

  • add missing :guilabel:'s 😈
  • wording/grammar: I caught a number of instances where the technical details were too wordy, vague, or the instruction got lost / wasn’t clear. Some words are strange like “hit” instead of “click” or “choose”.
  • headings: especially the h1 so they follow convention re:guidelines:headings
  • Consider rephrasing all hypothetical narratives (e.g. “imagine if…”). Would stick to third-person instructional w/ time order language, if possible. “What if” scenarios are more helpful when visually illustrated with video or long-form blog articles, however for software documentation, this will interrupt ability to skim and absorb instructions which are supposed to be clear and easy to find.
  • Similarly, would also reword/remove all first-person and second-person familiar statements and stick with third-person instructional.
  • images: check all for HD resolution, at or around 768 pixel breakpoint in width, and are compressed. Are there any images that need to be reshot?
  • images: are they actually showcasing the feature being written about? Some aren’t clear.
  • remove unnecessary images, or surround them with new blocks of descriptive copy so the writing is leading the document instead of the visuals re: guidlines:images

Forward-Port-Of: #2556

@robodoo
Copy link
Collaborator

robodoo commented Oct 25, 2022

@fw-bot
Copy link
Collaborator Author

fw-bot commented Oct 25, 2022

This PR targets 16.0 and is part of the forward-port chain. Further PRs will be created up to master.

More info at https://github.com/odoo/odoo/wiki/Mergebot#forward-port

@robodoo robodoo closed this in edf9e1a Oct 25, 2022
@robodoo robodoo temporarily deployed to merge October 25, 2022 17:55 Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants