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)

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.

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.

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

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.

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"

will improve collaboration

2012. Microsoft Writing Style Guide. https://docs.microsoft.com/en-us/style-guide/welcome/.

You should link abundantly to other content. Wikipedia articles provide some of the best examples of “every page is page one” style.

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

an example of a product that is not yet ready to be sold a demo version of the software

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."

Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was..."

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.

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…”

andrewdeandrade commented on Jul 30, 2015

andrewdeandrade commented on Jul 31, 2015

Not only were his subjects idiosyncratic, but his style was poetic, aphoristic, dra~atic, and colorful.