220 Matching Annotations
  1. Dec 2024
    1. Should we optimize for searching or browsing?¶ Documentarians may have to determine whether users search or browse for content of interest. What you decide may influence how to focus your resources: SEO and search tools or navigation aids. The resolution to this may depend on your users and what they’re looking for… and also your product interface. Some users, those who frequently search online for content, may prefer to search through your documentation (for example, spending 70% of their time on search and 30% navigation). Other users may prefer to use your site’s navigation system (for example, 30% search and 70% navigation). Nonetheless, some documentarians assume that searching is the primary method that all users rely on. Some indicate that it’s important to have both methods available for the users to select what they want to do. Information architecture (IA) helps a docs team to develop content in a structured and comprehensive manner. A navigation methodology can implement the IA of the documentation system. So, if your team has developed a structure for the content, you can use it as a navigation device for your readers. As one person indicated: No documentation should be random pages of text. Readers use the structure to learn relationships between different features, use cases, or topics. Searching and browsing are complementary actions. The method used by any one person may depend on different factors and users may use both. Offer the best of both to satisfy your readers. Search-related resources Search platform tips for documentation websites (WTD Newsleter) Making documentation discoverable in search engines (WTD video) Search engine optimization (SEO) for documentation (WTD page) Information Foraging (Nielsen Norman Group) Navigation- and IA-related resources Many articles available from Nielsen Norman Group Building navigation for your doc site: 5 best practices (WTD video) Complete Beginner’s Guide to Information Architecture (UX Booth) How To Make Sense of Any Mess (book by Abby Covert)
  2. Nov 2024
    1. TRSP Desirable Characteristics The repository is managed on well-supported operating systems and other core infrastructural software and hardware appropriate to the services it provides to its Designated Community.

  3. Oct 2024
    1. by porting ffmpeg to the zig build system, it becomes possible to compile ffmpeg on any supported system for any supported system using only a 50 MiB download of zig. For open source projects, this streamlined ability to build from source - and even cross-compile - can be the difference between gaining or losing valuable contributors.
  4. Sep 2024
    1. For all audiences and in most content, use intelligent or intelligence to describe or talk about the benefits of AI.In UI, use intelligent technology to describe the underlying technology that powers AI features.

      I think this is a good example of a misleading marketing ploy that shouldn't exist in technical documentation.

  5. Aug 2024
    1. Their success from a technical aspect was based in part on separating the camera from the sound recording device (David used a Nagra) by accurately controlling the speed of the camera and the tape recorder, allowing the two devices to be moved independently with respect to each other, an impossibility in commercially available equipment at the time. Long takes with ordinary equipment of the era would invariably lose synchronization.
    1. Monopoly is not played on a cartesian plane. It's played on a directed circular graph. Therefore, it is inappropriate to use the Euclidean distance metric to compare the distances between places on the board. We must instead use minimum path lengths. Example: If we used Euclidean distance, then you would have to agree that the distance between, say, Go and Jail is equal to the distance between the Short Line and the Pennsylvania Railroad. Clearly, this is not the intention. In your example, the "nearest railroad" would be the railroad square having the shortest path from wherever you stand. With the game board representing a directed graph, there are no "backwards" paths. Thus, the distance from the pink Chance square to the Reading railroad is not 2. It's 38.
  6. Jun 2024
    1. TensionThe ability to see like a data structure afforded us the technology we have today. But it was built for and within a set of societal systems—and stories—that can’t cope with nebulosity. Worse still is the transitional era we’ve entered, in which overwhelming complexity leads more and more people to believe in nothing. That way lies madness. Seeing is a choice, and we need to reclaim that choice. However, we need to see things and do things differently, and build sociotechnical systems that embody this difference.This is best seen through a small example. In our jobs, many of us deal with interpersonal dynamics that sometimes overwhelm the rules. The rules are still there—those that the company operates by and laws that it follows—meaning there are limits to how those interpersonal dynamics can play out. But those rules are rigid and bureaucratic, and most of the time they are irrelevant to what you’re dealing with. People learn to work with and around the rules rather than follow them to the letter. Some of these might be deliberate hacks, ones that are known, and passed down, by an organization’s workers. A work-to-rule strike, or quiet quitting for that matter, is effective at slowing a company to a halt because work is never as routine as schedules, processes, leadership principles, or any other codified rules might allow management to believe.The tension we face is that on an everyday basis, we want things to be simple and certain. But that means ignoring the messiness of reality. And when we delegate that simplicity and certainty to systems—either to institutions or increasingly to software—they feel impersonal and oppressive. People used to say that they felt like large institutions were treating them like a number. For decades, we have literally been numbers in government and corporate data structures. BreakdownAs historian Jill Lepore wrote, we used to be in a world of mystery. Then we began to understand those mysteries and use science to turn them into facts. And then we quantified and operationalized those facts through numbers. We’re currently in a world of data—overwhelming, human-incomprehensible amounts of data—that we use to make predictions even though that data isn’t enough to fully grapple with the complexity of reality.How do we move past this era of breakdown? It’s not by eschewing technology. We need our complex socio-technical systems. We need mental models to make sense of the complexities of our world. But we also need to understand and accept their inherent imperfections. We need to make sure we’re avoiding static and biased patterns—of the sort that a state functionary or a rigid algorithm might produce—while leaving room for the messiness inherent in human interactions. Chapman calls this balance “fluidity,” where society (and really, the tech we use every day) gives us the disparate things we need to be happy while also enabling the complex global society we have today.
  7. May 2024
  8. Apr 2024
  9. Mar 2024
    1. We can't use algorithms to filter for quality because they're not designed to. They're designed to steer you towards whatever's most profitable for their creators.That puts the onus on us, as users, to filter out the noise and that is increasingly difficult.
  10. Feb 2024
    1. Die Selbstverpflichtungen der Regierungen zur Dekarbonisierung reichen bei weitem nicht aus. Ein Bericht, der von den Vereinten Nationen als Grundlage für die kommende COP28 publiziert wurde, ergibt, dass 2030 etwa 20 bis 23 Gigatonnen mehr CO<sub>2</sub> emittiert werden sollen, als mit dem 1,5 °-Ziel verträglich wäre. Zum ersten Mal wird in einem offiziellen UN-Dokument das Ende der Nutzung fossiler Brennstoffe gefordert. https://www.theguardian.com/environment/2023/sep/08/un-report-calls-for-phasing-out-of-fossil-fuels-as-paris-climate-goals-being-missed

      Bericht: https://unfccc.int/sites/default/files/resource/EMBARGOED_DRAFT_Sythesis-report-of-the-technical-dialogue-of-the-first-global-stocktake.pdf

      Bericht: https://unfccc.int/documents/631600

    1. Der CO<sub>2</sub>-Gehalt der Atmosphäre wird 2024 weiter steigen, so dass die vom IPCC erarbeiteten Pfade, um das 1,5°-Ziel einzuhalten, nicht mehr eingehalten werden können. Das ergibt sich aus einer Studie des britischen Met Office, die sich auf die Daten des Mauna Loa-Observatoriums in Hawai stützt. (Die obere Grenze der Unsicherheitsbereiche dieser Pfade ist erreicht, selbst wenn der El-Niño-Einfluss abgezogen wird. Ein Einhalten der Pfade würde ein sofortiges Absinken des CO<sub>2</sub>-Gehalts erfordern.) https://www.liberation.fr/environnement/climat-les-concentrations-de-co2-cette-annee-menacent-la-limite-de-15c-daugmentation-globale-des-temperatures-20240119_6JIALPQDBNADFGNHS4MVDXR5QA/?redirected=1

      Animation: https://youtu.be/RYPDvTWDi0E?si=wWEUnypFxQO8M9D7

      Bericht: https://www.metoffice.gov.uk/research/climate/seasonal-to-decadal/long-range/forecasts/co2-forecast-for-2024

  11. Jan 2024
    1. Wirth himself realized the problems of Pascal and his later languages are basically improved versions of Pascal -- Modula, Modula-2, and Oberon. But these languages didn't even really displace Pascal itself let alone C -- but maybe if he had named them in a way that made it clear to outsiders that these were Pascal improvements they would have had more uptake.

      Modula and Oberon should have been codenames rather than independent projects.

    1. 每個語言都有自己的一組音位,這也就是這個語言的語音系統[4],音位可用來研究某個特定語言中如何將音組合成詞。音位有時被譯為「音素」[5],然而音素一詞在中文裡的用法較為混亂,不一定都是指音位。

      很高興看到台、中、港兩國三地的維基百科,不約而同把phoneme正名為「音位」而非「音素」。另外,星馬澳也如此。唯一「不合群」的漢字用法是日語,稱之為「音素」,這對台灣的譯名影響不小。

      建議從今起,大家努力建立共識,一概把phoneme稱作「音位」、把phonemics稱作「音位學」,一勞永逸,與有歧義的詞「音素」區分開來。

      很不幸,在台灣、正體中文的文獻中,「音素」一詞既可能指phone,也可能指phoneme,而區分兩者的能力又是語音學(phonetics)、音位學(phonemics)的重頭戲!因爲術語詞彙的翻譯不統一而造成學習和理解的混亂,得不償失。

      很支持臺灣雙語無法黨提倡PA(phonemic awareness音位意識)的宗旨,但黨主席蕭博士對外一貫把PA中的phoneme稱作「音素」,就容易和phone(亦可稱「音素」)混淆。建議一起努力大聲說出「音位」。

  12. Dec 2023
  13. Oct 2023
    1. Messages are delineated by newlines. This means, in particular, that the JSON encoding process must not introduce newlines within a message. Note however that newlines are used in this document for readability.

      Better still: separate messages by double linefeed (i.e., a blank line in between each one). It only costs one byte and it means that human-readable JSON is also valid in all readers—not just ones that have been bodged to allow non-conformant payloads under special circumstances (debugging).

  14. Sep 2023
    1. If IFS is unset, or its value is exactly <space><tab><newline>, the default, then any sequence of IFS characters serves to delimit words. If IFS has a value other than the default, then sequences of the whitespace characters space and tab are ignored at the beginning and end of the word, as long as the whitespace character is in the value of IFS (an IFS whitespace character). Any character in IFS that is not IFS whitespace, along with any adjacent IFS whitespace characters, delimits a field. A sequence of IFS whitespace characters is also treated as a delimiter. If the value of IFS is null, no word splitting occurs.
    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.
  15. Aug 2023
    1. Another way I get inspiration for research ideas is learning about people's pain points during software development Whenever I hear or read about difficulties and pitfalls people encounter while I programming, I ask myself "What can I do as a programming language researcher to address this?" In my experience, this has also been a good way to find new research problems to work on.
  16. Jul 2023
    1. "It's easier to ask forgiveness than it is to get permission."

      "It's easier to ask forgiveness than it is to get permission."

    1. Also, for those who for some reason prefer curly brackets over Python-style indenting, it is also possible to write:

      Good and sensible.

  17. May 2023
    1. articulates requirements for readability sating that identifiers must be: Any printable characters from the Universal Character Set of ISO/IEC 10646 (ISO 2012):UTF-8 encoding is required; Case insensitive:Only ASCII case folding is allowed.

      {UTF-8} {ASCII Case Folding}

    1. almost all beginners to RDF go through a sort of "identity crisis" phase, where they confuse people with their names, and documents with their titles. For example, it is common to see statements such as:- <http://example.org/> dc:creator "Bob" . However, Bob is just a literal string, so how can a literal string write a document?

      This could be trivially solved by extending the syntax to include some notation that has the semantics of a well-defined reference but the ergonomics of a quoted string. So if the notation used the sigil ~ (for example), then ~"Bob" could denote an implicitly defined entity that is, through some type-/class-specific mechanism associated with the string "Bob".

  18. Jan 2023
    1. Now, if you try to parse a date (using the pandas.to_datetime() function) that lies outside this range, we get the above ParseError.

      The datetime type in pandas can only take values inside a given range, for example, dates less than 1677-09-21 and greater than 2262-04-11 cannot be used in Pandas. Is this due to the bit size the datetime[ns] type uses in Pandas?

    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"
    1. Patch based systems are idiotic, that's RCS, that is decades old technology that we know sucks (I've had a cocktail, it's 5pm, so salt away).Do you understand the difference between pass by reference and pass by value?

      Larry makes a similar analogy (pass by value vs pass by reference) to my argument about why patches are actually better at the collaboration phase—pull requests are fragile links. Transmission of patch contents is robust; they're not references to external systems—a soft promise that you will service a request for the content when it comes. A patch is just the proposed change itself.

    1. how important is the concrete syntax of their language in contrast to

      how important is the concrete syntax of their language in contrast to the abstract concepts behind them what I mean they say can someone somewhat awkward concrete syntax be an obstacle when it comes to the acceptance

  19. Nov 2022
    1. The creators of Scrivener have taken a process that formerly had to be done manually by writers, and built a system of cues that make it easy and natural.
    1. The paradox of information systems[edit] Drummond suggests in her paper in 2008 that computer-based information systems can undermine or even destroy the organisation that they were meant to support, and it is precisely what makes them useful that makes them destructive – a phenomenon encapsulated by the Icarus Paradox.[9] For examples, a defence communication system is designed to improve efficiency by eliminating the need for meetings between military commanders who can now simply use the system to brief one another or answer to a higher authority. However, this new system becomes destructive precisely because the commanders no longer need to meet face-to-face, which consequently weakened mutual trust, thus undermining the organisation.[10] Ultimately, computer-based systems are reliable and efficient only to a point. For more complex tasks, it is recommended for organisations to focus on developing their workforce. A reason for the paradox is that rationality assumes that more is better, but intensification may be counter-productive.[11]

      From Wikipedia page on Icarus Paradox. Example of architectural design/technical debt leading to an "interest rate" that eventually collapsed the organization. How can one "pay down the principle" and not just the "compound interest"? What does that look like for this scenario? More invest in workforce retraining?

      Humans are complex, adaptive systems. Machines have a long history of being complicated, efficient (but not robust) systems. Is there a way to bridge this gap? What does an antifragile system of machines look like? Supervised learning? How do we ensure we don't fall prey to the oracle problem?

      Baskerville, R.L.; Land, F. (2004). "Socially Self-destructing Systems". The Social Study of Information and Communication Technology: Innovation, actors, contexts. Oxford: Oxford University Press. pp. 263–285

    1. @stephen@social.stephenfry.com

      This is where it starts getting ridiculous.

      First, rather than social.stephenfry.com, stephenfry.com should be sufficient. Look at email. I can set my MX records to point wherever I want. I don't actually have to have a server with A records to field the email traffic.

      Secondly, the @stephen part is superfluous, too! This is something where Mastodon et al had years (decades!) of hindsight to take care of this, and they still messed it up.

  20. Oct 2022
  21. Sep 2022
    1. Such schemas cannot easily be refactored without removing the benefits of sharing. Refactoring would require forking a local copy, which for schemas intended to be treated as an opaque validation interface with internal details that may change, eliminates the benefit of referencing a separately maintained schema in the first place.
    1. The LISP part, though, is not going well. Porting clever 1970s Stanford AI Lab macros written on the original SAIL machine to modern Common LISP is hard. Anybody with a knowledge of MACLISP want to help?
  22. Aug 2022
  23. Jun 2022
    1. Want to animate navigations between pages? You can’t (yet). Want to avoid the flash of white? You can’t, until Chrome fixes it (and it’s not perfect yet). Want to avoid re-rendering the whole page, when there’s only a small subset that actually needs to change? You can’t; it’s a “full page refresh.”

      an impedance mismatch, between what the Web is (infrastructure for building information services that follow the reference desk model—request a document, and the librarian will come back with it) versus what many Web developers want to be (traditional app developers—specifically, self-styled product designers with near 100% autonomy and creative control over the "experience")—and therefore what they want the Web browser to be (the vehicle that makes that possible, with as little effort as possible on the end of the designer–developer)

    1. Technical specs have immense benefits to everyone involved in a project: the engineers who write them, the teams that use them, even the projects that are designed off of them

      Benefits: 1. as developer, easy to solve problem 2. as team, easy to do team work 3. as Project manager, easy postmortems

  24. May 2022
    1. Because we didn’t have real marketing people, we updated the product to became more and more interesting to us, the developers, and less interesting to potential buyers.
    1. an acknowledgement of network effects: LP is unlikely to ever catch on enough to be the majority, so there needs to be a way for a random programmer using their preferred IDE/editor to edit a "literate" program

      This is part of the reason why I advocate for language skins for comparatively esoteric languages like Ada.

  25. Apr 2022
  26. 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.
  27. 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.

    1. What does a Functional Design have to offer? https://en.itpedia.nl/2019/01/16/wat-heeft-een-functioneel-ontwerp-te-bieden/ A functional design is a specification of the functions of the software that the end_users have agreed to. Many companies have a software_developer handbook that describes what topics a functional design should cover. This article looks at the steps of functional design in the context of software development.

  28. Nov 2021
  29. 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.

  30. 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."
  31. Sep 2021
    1. Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..."
    1. Vice versa, many researchers and practitioners who are mainly interested in human-centered social constructs choose to ignore the to them often alienating world of technical systems design.
    2. human-centered aspects that predominate in community informatics, like ethics, legitimacy, empowerment, and socio-technical design
    3. socio-technical
  32. Aug 2021
    1. "Whether those slashes were forward slashes or back slashes didn't affect how the Web worked," he says, "but it does affect how other developers react to it
  33. Jun 2021
  34. May 2021
    1. Hey, I'm a PhD in [field] and do [whatever] professionally. Before calling you, I've narrowed down the problem to [something on their end], so that's what needs to be addressed. If I could speak to an engineer about [specific problem], that'd be great; but if we've gotta walk through the script, let's just knock it out quickly. If they end up requiring the script, then the best way to use your expertise is to run through it quickly. Keep the chit-chat to a minimum and just do the stuff efficiently. If they start describing how to perform some step, you might interrupt them with, "Got it, just a sec.", then let them know once you're ready for the next step.
    2. So what can you do to demonstrate your technical knowledge? Well, you are doing the right thing by using the correct technical terms. That will give an indication to the person handling the ticket. Explicitly explaining your role as the administrator or developer should also help.
    3. From experience I can say that professionals will be more forgiving if you go through things at a basic level than amateurs who have no idea what you're talking about, so people will probably err on the side of caution and not assume the customer has a high level of expertise.
  35. Apr 2021
    1. (Yes, I realize from a technical, end-user perspective this really doesn't matter.)

      The word "technical" in this sentence doesn't seem to belong or to clarify anything. I think it would be clearer without it.

      But I think I understand what he's saying, which is that technical details don't matter to the end user. They only know/see/care if it works or not.

    1. If you want to run a full fletched linux OS on the ipad an option is to jailbreak the ipad and try to install linux. This is hard because Apple does not want you to and a failed installation might render the ipad useless. Also you will not be able to run any iOS apps anymore obviously.

      new tag?: jailbreaking a device

  36. Mar 2021
    1. I consider systemd/user as a good alternative for dex's autostart functionality and switched to it recently. In particular, systemd solves the issue of dex losing control over the started processes which causes processes to live longer than the X session which could cause additional annoyances like reboots taking a lot of time because the system is waiting for the processes to terminate.
    1. Refactoring is a means of addressing the problem of software rot. It is described as the process of rewriting existing code to improve its structure without affecting its external behaviour.
  37. Feb 2021
    1. The Subprocess macro will go through all outputs of the nested activity, query their semantics and search for tracks with the same semantic.
    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.
  38. Jan 2021
    1. JSONP is a relic of the past and shouldn’t be used due to numerous limitations (e.g., being able to send GET requests only) and many security concerns (e.g., the server can respond with whatever JavaScript code it wants — not necessarily the one we expect — which then has access to everything in the context of the window, including localStorage and cookies).
    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…”
  39. Dec 2020
  40. Nov 2020
    1. this is treated as debt work for of us and that's usually tackled during the first week in the milestone (roughly the first week in the month)
  41. 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:
      
      ...
      
    1. And if they are a technical debt - how do measure up how much you can borrow so you can afford the repayments?
    2. debt ... which is not a straight bad thing but something that could provide some "short term financing" get us to survive the project (how many of us could afford to buy a house without taking out the mortgage?).
    3. But recently I started to think about default values as some sort of a technical debt ... which is not a straight bad thing but something that could provide some "short term financing" get us to survive the project
  42. Sep 2020