wissel.net

Usability - Productivity - Business - The web - Singapore & Twins

By Date: December 2020

What constitutes "good" (software) documentation?


Software ocumentation is a sticky issue and tends to escalate rather quickly in opinion matches, fighting over what is needed, what is missing and what should be different.

Looking at it closer I see 3 main dimentions:

  • audience
  • content
  • format

Each documentation artefact has a sweet spot in this cube as well as no-go zones (e.g. a business user watching a live coding recording?).

Any individual can and will fit into one or more audience, as each artefact will fit into one or more content categories. So good navigation and cross references are essential

Documentation MindMap


Read more

Posted by on 29 December 2020 | Comments (0) | categories: Software

Software distribution


Just download the binaries and run the installer. Would you need anything else for software distribution?

The rise of the AppStore

Mobile devices showed us the trend. Your Android device will load new apps from Google Play or Huawei's AppGallery (or any of the alternatives). On iOS, padOS, watchOS or tvOS, it is Apple's AppStore.

In the middle tier, Windows and macOS, the success is a mixed bag. Despite all attempts (Apple I'm looking at you), the bulk of apps are still "download and install". So each app has to implement its own update check (Unless you use Homebrew with its heritage in Linux).

In the enterprise this "poll request" approach is supplemented or surplanted by a push approach using tools like jamf (Mac only) or BigFix (cross platform).

Servers and components

On Windows there is Windows Server Update Services, which keeps your servers neat and updated and can update 3rd party software too.

On Linux package managers have been established for quite a while any you find most software in rpm, deb or Snap format. Local package managers can be set up to install packages automatically based on criteria (e.g critical updates)

For Docker there is the Hub, for Java based packages Maven central and for JavaScript based applications the NPM registry

In the enterprise environment, you can find Artifactory or Nexus Repository as well as cloud based solutions like Azure Artifacts, AWS CodeArtifact or DigitalOcean Container Registry

Your application?

With the ready availabily of repositories (App stores are nothing more than repositories with UI and billing), what does that demand from your app?

In short: make it easy to accquire and update your code

  • on mobile swallow the frog and publish to an app store
  • on desktops: if your main customers are individuals, the app store might save you the headache of a good update strategy. When companies are your target: make it jamf / WSUS friendly
  • on servers: a package repository, inlcuding the ability to deploy to a corporate repository is a must. This applies to updates too
  • components: you need a registry. Should you consider none of the established public ones as suitable, provide your own

Of course, you can consider retro a charm and be left behind

As usual YMMV


Posted by on 14 December 2020 | Comments (2) | categories: Software