Explainers start with a description of user problem(s) to be solved. Depending on the problem(s), the boundaries of what to solve or not may be unclear, or solutions for subset(s) of the problem(s) may be significantly simpler or more practical than solutions for the full possibilities of the problem(s).

We should document a way (or ways) for Explainer authors to explicitly communicate what they consider out of scope for a particular Explainer, either by description or specific example(s).

For example @martinthomson noted that currencies may not meet the documented criteria for solutions for the amount explainer.

Here are a few ways to document such out of scope aspects:

1. A brief “Out of scope: (inline list of examples and/or classes thereof).” sentence at the end of section 1, to explicitly communicate what problems the explainer is not trying to solve
2. A brief "Out of scope: solutions that (inline list of undesired characteristics, dependencies, or classes thereof)" sentence or paragraph at the end of section 2, to explicitly communicate what kinds of solutions the explainer is not exploring
3. Rephrasing the out of scope aspect as a caveat of a proposed solution, and adding that to section 8 caveats, shortcomings, etc.

A good next step here would be some amount of experimenting with adding out of scope aspects to existing explainers in this repo, then commenting on this issue with those empirical examples. If good patterns emerge, we can document them as explicit guidance in our Explainers README.

One of the biggest challenges with tools for making things, even specific to making web things, is there are so many tools to choose from. Nearly every tool has a learning curve to overcome before being able to use it efficiently. With proficiency, comes the ability to pursue more efficient use of tools, and find limitations, papercuts, or outright bugs in the tools. If it’s an open source tool or you know its creator you can file or submit a bug report or feature request accordingly, which might result in an improved tool, eventually, or not. You have to decide whether any such tool is good enough, with tolerable faults, or if they’re bad enough to consider switching tools, or so bad that you are compelled to make your own.

This post is my entry for the 2024 July IndieWeb Carnival theme of tools, hosted by James G., and also syndicated to IndieNews.

Criteria

I have many criteria for how I choose the tools I use, but nearly all of them come down to maximizing trust, efficiency, and focus, while minimizing frustration, overhead, and distraction. Some of these are baseline criteria for whether I will use a tool or not, and some are comparative criteria which help me decide which tool I choose from several options.

Trustworthy tools should be:

• Predictable — it should be clear what the tool will do
• Dependable — the tool should “just work” as close to 100% of the time as possible
• Acting as you direct it — the tool should do exactly what you direct it to do, and not what other parties, such as its creator or service provider, direct it to do
• Forgiving — if you make a mistake, you should be able to undo or otherwise correct your mistake
• Robust enough to keep working even when not used for a while

Efficient tools should:

• Be quick and easy to start using
• Be responsive, with as low a latency as possible, ideally zero perceptible latency
• Reduce the work necessary to complete a task, or complete multiple tasks with same amount of work otherwise
• Reduce the time necessary to complete a task, or complete multiple tasks in the same amount of time otherwise
• Be quick and easy to shut down, or otherwise put away
• Use little or no energy when not in use

Focused and focusing tools should

• Provide clear features for accomplishing your goals
• Encourage or reinforce focusing on your tasks and goals
• Never interrupt you when you are using the tool to accomplish a task

Bad tools can have many sources of frustration, and nearly all of these involve inversions of the desirable qualities noted above. Frustrating tools are less predictable, work only some of the time, randomly do things because some other party directed them to (like auto-upgrade), ask you to confirm before doing actions because they have no capability to undo, or stop working for no particular reason.

Inefficient tools take too long to be “ready” to use, are unresponsive of otherwise have a delay when you provide input before they respond, cause you more work to complete a task, or make you take more time than simpler older tools would, require waiting for them to shut down, or use energy even when you are not doing anything with them.

Unfocused tools have many (nearly) useless features that have nothing to do with your goals, encourage or distract you with actions irrelevant to your tasks or goals, or interrupt you when you are working on a task.

Baseline Writing Tools

Examples of tools that satisfy all the above:

• Pencil (with eraser) and paper
• A typewriter (ideally with a whiteout band) and paper

That’s it, those are the baseline. When considering an alternative tool for similar tasks, such as writing, see if it measures up to those.

Tools I Like Using

For myself, I prefer to use:

• BBEdit for writing, which requires near zero maintenance for years of reliable use, for both prose (and markup) for my posts, and code for my personal website
• MediaWiki based wikis for collaborative text authoring like on:
  • indieweb.org
  • wiki.mozilla.org
  • www.w3.org/wiki/
  • and of course Wikipedia

Tools I Tolerate Using

I do also use the iOS and MacOS “Notes” app notes to sometimes write parts of posts, and sync text notes across devices, both of which have unfortunately become just frustrating enough to be barely tolerable to use.

iOS Notes (as of iOS 17.5) are buggy when you scroll them and try to add to or edit the middle of notes. MacOS Notes have a very annoying feature where it tries to autocomplete names of people in your contacts when you type even just the first letter of their name or an @-sign, when you rarely if ever want that. MacOS Notes also forces anything that starts with a # (hash or pound) sign into a weird auto-linked hashtag that is nearly useless and breaks text selection.

There are no options or preferences to turn off or disable these annoying supposedly “helpful” automatic features.

There’s definitely an opportunity for a simple, reliable, easy to sync across devices, plain text notes application to replace iOS and MacOS notes, that doesn’t require signing up to some third-party service that will inevitably shut down or sell your information to advertisers or companies training their LLMs or leak your information due to poor security practices.

Similarly I also frequently use Gmail and Google Docs in my day-to-day work, and I’ve grown relatively used to their lagginess, limitations, and weird user interface quirks. I use them as necessary for work and collaboration and otherwise do my best to minimize time spent in them.

Better Tools

I have focused primarily on writing tools, however I have made many distinct choices for personal web development tools as well, from writing mostly directly in HTML and CSS, to bits in PHP and JavaScript, rather than frameworks that demand regular updates that I cannot trust to not break my code. I myself try to build tools that aspire to the criteria listed above.

At a high level, new tools should provide at least one of three things:

1. Higher efficiency and/or quality: tools should help you do what you already could do, but faster, better, cheaper, and more precisely
2. Democratization: tools should help more people do what only a few could do before
3. Novelty: tools should help you do new things that were either impossible before or not even imagined

Mostly I prefer to focus on the first of those, as there are plenty of “obvious” improvements to be made beyond existing tools, and such improvements have much more predictable effects. While democratization of tools is nearly always a good thing, I can think of a small handful of examples that demonstrate that sometimes it is not. That’s worth a separate post.

Lastly, tools that help accomplish novel tasks that were previously impossible or not even imagined perhaps have the greatest risks and uncertainty, and thus I am ok with postponing exploring them for now.

I wrote a few general thoughts on what tools and innovations to pursue and considerations thereof in my prior post: Responsible Inventing.

Referencing Articles

Articles also written about this topic that reference this article.

1. 2024-08-01 Tom Morris: A world run by tools

The proposed Working Group (WG) charter contains boiler-plate "Success Criteria" which though excellent for creating strictly technical specifications intended for interoperable implementations that users can choose and use, and are far more strict than necessary for the Web Sustainability Guidelines (WSG), and may instead have the unintended consequence of removing helpful guidance that otherwise cannot pass that high bar of interoperable implementations.

Assuming that issue 105 is resolved to create an Interest Group (IG) instead of a WG, one subsequent necessary step is to define explicit Success Criteria for the WSG itself.

The Success Criteria for the WSG need to be rewritten to encapsulate consensus goals for the WSG, e.g. having a maximally impactful WSG as soon as possible that can be iteratively improved.

We’d like to see a broad spectrum of any and all possible sustainable web guidance in the guidelines, from known measurable highly impactful techniques, to ideas worth exploring for more sustainable adoption and use of existing web technologies. We leave it up to the editors and contributors to the charter to help define Success Criteria for publishing a WSG Statement that takes into account the goals of the WSG, and the broad spectrum nature of the WSG.

Our hope is that an explicit Success Criteria for a WSG Statement will help guide and focus the IG, help the IG determine when the WSG Note is ready for an Advisory Committee (AC) poll to take it to Statement, as well as provide a methodology for the Advisory Committee (AC) to evaluate a WSG Note to help determine if it passes the criteria that was documented in advance.

Problem statement: Currently it is very difficult if not impossible in some cases to discover from a Working Group charter:

• what were the poll results that helped create that charter?
• was there any feedback, or objections formal or otherwise?
• how was any dissent handled?
• what were the changes if any from the polled charter to the adopted charter?
• was there any follow-up repolling of poll respondents and what were the results?

This makes it difficult for W3C members, and especially difficult for newcomers to W3C, to understand the context and work that went into chartering a working group, why some things in a charter are the way they are, and a deeper understanding of how & why the working group was created.

Proposed solution: A good way to provide transparent and historically discoverable paths to these artifacts of chartering working groups would be better cross-hyperlinking/discoverability (follow-your-nose style) explicit links from, to, and between the following:

• Working Group (WG) charters (both current and all previous)
• The Advisory Committee (AC) charter WBS poll (and results) that presumably approved each charter, with perhaps also links to prior charter polls that failed.
• A brief document summarizing critical feedback (noted issues, requested changes, required (Formal Objection) changes) on each charter poll when it closed
• A thorough document explaining how each item of critical charter feedback was handled. Charter proposals need a “Disposition of comments” similar to a Candidate Recommendation (CR) that is Proposed (PR) to transition to a Recommendation.
• What precise changes (diffs) were made between a proposed (polled) and eventually adopted charter to handle each item of critical feedback
• If any such changes were made between a polled and eventually adopted charter, when were the folks who voted on the proposed charter repolled with the modified proposed charter with those changes (dated permalink to modified proposed charter as of time of repolling)
• What were the repolling responses both in aggregate (totals x for, y against, z abstain) and individually (explicit +1/-1, passive or active abstention), same granularity as the original proposed charter poll Results Page
• When/where was the repolling result announced (permalink to email)

cc: @ianbjacobs, @dontcallmedom

Rather than a working group (WG), a Sustainable Web Interest Group (IG) with open participation would better enable the Web Sustainability Guidlines (WSG) to have a larger impact sooner, with broader support.

Proposal: rewrite the current proposed SustyWeb charter as charter for a SustyWeb IG and provide a plan for publishing the WSG as a Note, rapidly iterating similar to how the Community Group is already iterating on the WSG Report, with the eventual goal of publishing an AC-approved W3C Statement to give it more formal standing.

An IG would have less process than a WG. It would for example avoid things like patent-related procedures, disclosures, etc. which should be unnecessary for the WSG.

The IG charter could also define custom success criteria for a WSG Statement that better reflects the varied needs of providing a broad spectrum of sustainability guidelines. A broad set of sustainability guidelines would better achieve sustainability goals than subsetting or restricting the guidelines to only those that pass a more precisely objective testability bar that is expected for purely technical specifications for interoperable independent implementations.

At a high level the WSG is also more similar to the Ethical Web principles, which itself is destined (eventually) for a W3C Statement.

cc: @ianbjacobs, @caribouW3

Similar to its rel=me checking support (validator), IndieWebify should support parsing, checking, and advising how to improve any rel=author (https://microformats.org/wiki/rel-author) links found on a page.

IndieWebify should look for and check both:

<a rel="author" href="https://…">

and

<link rel="author" href="https://…">

tags, and display a list of all of them found on a particular page, along with any additional information about each one (e.g. type=, title=, and hreflang= attributes).

Ideally it should also check for a valid representative h-card at the destination of a rel=author link.

This is worth implementing both as its own IndieWebify feature (especially so software & services like Mastodon could test an implementation), and as a building block towards implementing a complete authorship validator (issue #6).

Similar to its h-entry checking support (validator), IndieWebify should support parsing, checking, and advising how to improve your h-feed (https://microformats.org/wiki/h-feed), ideally re-using the existing h-entry checking code to also validate all h-entry items found inside the h-feed.