52 Matching Annotations
  1. Sep 2023
    1. It seems that the method is a direct equivalent of a.fdiv(b).ceil, and as such, annoyingly unnecessary, but fdiv, due to floating point imprecision, might produce surprising results in edge cases
    1. As "module" is more generic concept than "class", the name misleadingly implies that either this method doesn't returns refined modules, or modules can't be refined. This is obviously not true and trivially disproved: module Refs refine Enumerable do def foo = puts 'foo' end end Refs.refinements[0].refined_class #=> Enumerable. Which is, well, not a class. # The refinement is usable, so it is not a mute concept: using Refs [1, 2, 3].foo # prints "foo" successfully I believe we refer to "modules" when some feature applies to modules and classes. Unless there is some deeper consideration for the current naming (I don't see justification in #12737, but I might miss something), the method should be renamed or aliased.
  2. Aug 2023
  3. May 2023
  4. Jan 2023
    1. The popular recommendation is that there should be between 40 and 75 characters per line. The findings of multiple studies conclude that "short line lengths are easier to read". Regarding learning and information retention: "Subjects reading the narrow paragraphs had better retention than those reading the wide paragraphs"
  5. Oct 2022
  6. Aug 2022
  7. Apr 2022
  8. Mar 2022
    1. You should link abundantly to other content. Wikipedia articles provide some of the best examples of “every page is page one” style.
  9. Jan 2022
    1. The nature of technical writing is explained in "The nature of technical writing". Technical communication is something we do every day without even noticing. Having strong communication skills is beneficial in all areas of one's life, from personal to professional. From a business standpoint, communication is key to every transaction. Communicating effectively allows others and yourself to understand information at a faster and more accurate rate. A lack of communication skills leads to frequent misunderstandings and frustration.

    2. Technical communication/writing is something that has been around for a very long time. The earliest examples belong to Aristotle and his dictionary of "philosophical terms" and his summary of the "Doctrines of Pythagoras". World War I is considered the "Golden Age" of technical writing due to advances in medicine and aerospace.

  10. Nov 2021
  11. dictionary.cambridge.org dictionary.cambridge.org
    1. an example of a product, especially a computer program or piece of recorded music, given or shown to someone to try to make them buy or support it: a software demo

      I prefer this to the Merriam-Webster definition.

  12. Oct 2021
    1. user n. When referring to the reader, use "you" instead of "user." For example, "The user must..." is incorrect. Use "You must..." instead. If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may want to access your database."
  13. Sep 2021
    1. Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..."
  14. Jun 2021
  15. May 2021
  16. Apr 2021
  17. Mar 2021
  18. Feb 2021
    1. Fewer screenshots means less maintenance work. If the product changes, the screenshots must change too, to remain helpful and prevent confusion. Lots of screenshots plus frequent product changes can cost a lot of time: keeping the docs in sync with the product can become unmanageable. A middle-ground approach is using text descriptions of UI elements, like “Click the START button”, as it’s easier to keep text descriptions matching the UI. And well-designed user interfaces and UI microcopy often mean that users don’t need screenshots to find their way through the product.
  19. Jan 2021
    1. The debate about whether a button or link should be used to download a file is a bit silly, as the whole purpose of a link has always been to download content. HTML is a file, and like all other files, it needs to be retrieved from a server and downloaded before it can be presented to a user. The difference between a Photoshop file, HTML, and other understood media files, is that a browser automatically displays the latter two. If one were to link to a Photoshop .psd file, the browser would initiate a document change to render the file, likely be all like, “lol wut?” and then just initiate the OS download prompt. The confusion seems to come from developers getting super literal with the “links go places, buttons perform actions.” Yes, that is true, but links don’t actually go anywhere. They retrieve information and download it. Buttons perform actions, but they don’t inherently “get” documents. While they can be used to get data, it’s often to change state of a current document, not to retrieve and render a new one. They can get data, in regards to the functionality of forms, but it continues to be within the context of updating a web document, not downloading an individual file. Long story short, the download attribute is unique to anchor links for a reason. download augments the inherent functionality of the link retrieving data. It side steps the attempt to render the file in the browser and instead says, “You know what? I’m just going to save this for later…”
  20. Nov 2020
  21. Oct 2020
    1. Look at their Readme:

      Well we have had a great time adding field validations, but there are validations that are tied up to the whole record we are editing than to a given field, for instance let's face this scenario:
      
      - You are not allowed to transfer more than 1000 € to Switzerland using this form (for instance: you have to go through another form where some additional documentation is required).
      
      - The best place to fire this validation is at record level.
      
      - Record validation functions accept as input parameter that whole form record info, and return the result of the validation (it accepts both flavours sync and promise based), let's check the code for this validator:
      
      ...
      
  22. Sep 2020
  23. Aug 2020
  24. Jan 2020
  25. Sep 2019
  26. Aug 2019
  27. Feb 2017
    1. Not only were his subjects idiosyncratic, but his style was poetic, aphoristic, dra~atic, and colorful.

      As far as our readings go, did we not just establish technical writing as the new fad?