manifoldco
Style guide - Tables and list
On route to overhauling the UX and standardizing output we need to decide what shape our tables and lists take in various situations (empty, one column, multiple column, multi-line table, etc)
Talking points
- What do our tables look like?
- Do we use headers? What do they look like?
- Are lists just tables with one column?
- Do one column tables have headers?
- How do we handle lists with asterisks (technically two column)
- How do we handle list data which is multi-line (such as worklog)
- Git log inspired format?
- What is our default approach to sorting?
- Do we offer filtering?
- Graceful degradation (no rich formatting, removing headers etc) for scripts
- Rely on system tools as much as possible (awk, grep)
- How do we denote different table row states?
- Critical vs non-critical?
- Automate-able vs manual
@ntassone @jbowes this will be informed by your discussion around work log
Also relates to https://github.com/manifoldco/torus-cli/issues/94
Worklog
Future formatting possibilities
Git log
$ git log
commit 093cb64d13a1ce401b2028920f9aa087566d8705
Author: Ian Livingstone <[email protected]>
Date: Thu Dec 8 09:05:09 2016 -0400
Update Changelog to include release date
commit ea91040cf54f9a7c0fc6b73e112a9d8f2c7d92f8
Author: Ian Livingstone <[email protected]>
Date: Wed Dec 7 18:43:24 2016 -0400
Update CHANGELOG
commit 7ae3310cb18b8f3cc485fb5a9024fcbdff4a0960
Merge: eec5212 6cba857
Author: Jeff Andersen <[email protected]>
Date: Wed Dec 7 15:17:50 2016 -0400
Merge pull request #138 from manifoldco/specificity-bool
Do not filter by specificity during torus ls
Git log oneline
$ git log --oneline
093cb64 Update Changelog to include release date
ea91040 Update CHANGELOG
7ae3310 Merge pull request #138 from manifoldco/specificity-bool
6cba857 Do not use credential set for torus ls as we do not want to filter by specificity
My opinion
Tables
Every table should have a header. I don't have a strong opinion of the style, but it should likely be formatted (bold/color), title case. Header is separated by either a newline or a dashed separator. Something like:
Id Name Description
12345678 John Smith This would be where the description goes for this item
and it would be word-wrapped when it gets too long
09876543 Sally Jones The other description begins here
I prefer not to have separating lines or characters, just spacing with text... feels clean.
My opinion
Lists
Depending on whether we implement a breadcrumb (ignore the style of it for now), we may need to use a header to explain what is being listed. For instance, listing services for an org with an without breadcrumb:
$ torus services list
Org > jeff
Services
www
api
worker
$ torus services list
Services for org: jeff
www
api
worker
This could look better with proper breadcrumb design.
Another option would be to not display any breadcrumb or context until -v is used.
$ torus services list
www
api
worker
$ torus services list -v
Services for org: jeff
www
api
worker
Which I kinda like.
My opinion
Sorting
I feel like it should be alphabetical for object lists, and tables should be based on creation date (where applicable, otherwise serial desc)
Filtering
I think my opinion is captured in the description. Lets not make it our job to reimplement system tools in our product. Lets make it easy to disable/strip away excess output, and allow the users to use system tools like grep/awk to parse data.
I think my opinion is captured in the description. Lets not make it our job to reimplement system tools in our product. Lets make it easy to disable/strip away excess output, and allow the users to use system tools like grep/awk to parse data.
The problem with relying on system tools is that the user has to learn how to use these which tend to be esoteric and not standardized across implementations. We want all types of developers to be able to use our tooling -- not just user unix power users.
I think we'll need a compromise here or two approaches, one for simple use cases and another for complex ones.
cc @mattcreager
To clarify, the filtering is in response to tables specifically.. ie. getting rid of columns, or only showing certain ones. Something that tools like awk excel at.
Tables
I like spaces and newlines rather than dashes/separators, so +1. Here are a couple sketches of what color/formatting could do:
Bold headers at 60% opacity:
Bold headers with color:
Breadcrumbs as context with -v could be very useful.
Sketching out some ideas for formatting:
Brackets with level labels and arrows:
Brackets, no level labels, arrows:
Leading label, level labels and slashes:
