►
Description
Pedro Moreira da Silva, Staff Product Designer, walks through a heuristic evaluation of the UX Scorecard for “Author a pipeline: Look up reference”.
- Issue with links to resources: https://gitlab.com/gitlab-org/gitlab-design/-/issues/2359
- .gitlab-ci.yml keyword reference page: https://docs.gitlab.com/ee/ci/yaml/
A
Hi,
my
name
is
Pila
Mirada,
Silva
and
I'm
a
Staff
product
designer
at
gitlab.
Today,
I'm
going
to
walk
you
through
a
ux
scorecards,
heuristic
evaluation
that
I
did
for
our
documentation
website.
More
specifically,
the
gitlab
CI
reference
page,
where
we
have
all
of
the
keywords
for
configuring
CI
Pipelines.
A
So
this
is
the
page.
It's
a
very,
very
long
page,
almost
like
a
dictionary
of
everything
that
you
can
use
to
configure
your
CI
pipelines
and
jobs
using
this
file
in
a
repository
and
and
yeah.
Let
me
show
you
the
different
scenarios.
So,
first
of
all,
the
job
to
be
done
is
related
to
authoring
pipelines,
and
this
is
usually
performed
by
one
of
two
personas,
so
either
Priyanka
the
platform
engineer
or
Sasha
software
developer
and
the
job
to
be
done
is
when
authoring
a
pipeline.
A
I
would
like
to
know
what
are
the
available
keywords
and
their
descriptions,
so
I
can
set
up
my
pipeline
in
the
most
efficient
way
and
from
this
job
to
be
done.
There
are
many
steps
here.
One
of
it
is
to
look
up
the
reference
when
you're
building
maintaining
debugging
a
pipeline,
and
we
came
up
with
three
different
scenarios.
So
first
one
specific
keyword,
the
second
one
use
case
and
the
third
one
getting
started
and
there
are
slightly
different,
but
they
all
have
this
page
in
common,
the
keyword
reference
page.
A
A
So
with
this
in
mind,
the
first
stage
is
finding
the
reference
page
right
so
finding
this
documentation
page.
Where
I
have
this
information
and
the
steps
is,
you
know
you
can
either
use
the
search
engine
or
digitlab
docs
search
and
if
you
use
a
search
engine
like
Google,
you
get
these
top
results
and
the
first
results
is
the
keyword
reference,
and
this
is
just
searching
for
exactly
the
keyword,
we're
looking
for
that
specific
keyword.
That
is
the
changes
keyword,
so
gitlab
CI
pipeline
changes
returns.
A
A
This
one
choose
when
to
run
jobs,
it's
actually
probably
the
most
appropriate
one
that
talks
more
in
depth
about
how
you
can
use
that
keyword
to
basically
have
rules
and
conditions
around
when
to
run
the
jobs,
but
yeah
we're.
Looking
at
this
page,
the
keyword
reference
and
it's
the
first
result
and-
and
that
is
that
is
great,
so
here
a
user
might
think
the
top
search
results
seem
to
match
what
I'm
looking
for
and
it
meets
my
basic
expectations
regarding
search
engines,
so
I'm,
neutral,
I.
A
Think
one
opportunity
here
is
to
provide
perhaps
a
more
direct
link
to
the
CI
reference
page.
So
if
we
really
think
that
it's
the
most
visited
page
in
the
dark
side-
and
we
want
to
improve
how
people
get
to
it,
I
think
even
before
clicking
the
the
the
the
search
input
here,
we
could
have
a
link
to
it.
So
let
me
go
here
to
the
home
page.
A
A
We
have
this
nice
thing
that
when
you
click
on
the
search
input-
and
you
don't
type
anything-
we
have
this
popular
page
here,
which
is
nice,
but
it
can
be
easily
overlooked
and
if
it
is
really
the
most
visited
page,
we
might
want
to
make
that
even
more
visible
here,
but
we'll
make
recommendations
regarding
that.
After
this
video.
A
Then
the
next
step
is
when
we
finally
get
to
the
page
is
looking
for
the
keyword,
the
changes
keyword,
so
we
land
here
on
this
page
and
we
have
to
scroll
through
and
scan
the
page
and
there's
just
really
a
lot
a
lot
of
content
to
find
what
you're
looking
for.
So
you
know
the
user
thinks
I
scroll
a
bit
down
to
see
if
I
can
find
anything
related
to
what
I'm
looking
for,
but
I
feel
like
I
spent
a
lot
of
time.
A
Parsing
this
high
level
list
of
keywords
and
then
I
noticed
the
table
of
contents
on
the
right
side
of
the
page
here
right,
which
could
help
me
find
what
I'm
looking
for,
but
I
wish.
There
was
an
easier
way
to
find
the
keyword
so
the
whole
overall
feeling
is.
You
know
the
user
is
overwhelmed
by
a
lot
of
scrolling
and
trying
to
find
exactly
what
they're
looking
for
so
they
either.
A
You
know
try
to
do
it
on
on
their
own
and
scroll
down
or
potentially
one
opportunity
here
is
to
allow
filtering
the
content
here,
some
somehow
with
an
input
with
some
kind
of
controls
that
allows
readers
to
find
exactly
the
specific
keyword,
they're
looking
for
or
even
a
use
case
or
keywords
for
their
use
case.
We
will
see
in
a
minute.
A
So
in
this
case
the
heuristic
of
flexibility
and
efficiency
of
use
is
below
average,
because
it's
really
not
efficient
to
find
what
you're
looking
for,
so
to
find
the
keyword
again,
you
could
scroll
through
it
or
you
can
also
try
to
use
the
browser's
find
function.
So
when
you
do
that,
you
have
many
results.
73
results
for
the
changes
keyword.
A
Some
of
them
have
to
do
with
the
changes.
Keyword.
Others
not.
The
first
results.
Are
this.
This
keyword
here
only
changes
or
accept
changes.
So
if
I
do
jump
to
this
section
of
the
page,
it
explains
that
you
know
use
the
changes
keyword
with
only
to
run
a
job
or
accept
to
skip
a
job
when
you
get
push
event
modifies
a
file.
So
this
is
what
I'm
looking
for
this
is
the
exact
keyword.
The
problem
is
only
at
like
Midway.
A
You
get
this
this
paragraph
here,
which
I've
highlighted
in
red
that
changes
that
says
that
actually,
this
keyword
only
changes
and
accept
changes
are
not
maintain
anymore,
they're
not
being
actively
developed,
and
their
users
should
actually
rely
on
rules
changes
as
the
preferred
keyword
for
this
purpose.
So,
okay
I
found
this
it's
the
first
result,
but
actually
I
should
use
the
other
one.
So
this
is
not
great
and-
and
it's
it's
kind
of
tight
here
in
the
middle
I
would
hope
it
will
be
closer
to
the
top.
A
Interestingly,
if
I
go
here,
so
let
me
if
I
go
here
to
the
parent
section
of
only
changes.
So
let
me
show
you
here.
So
this
is
what
we
were
looking
at.
Only
changes
except
changes-
and
you
have
this
paragraph
here
in
the
middle,
saying
that
it's
not
being
actively
developed
if
I
scroll
up
a
bits
to
the
parent
section
that
contains
everything
regarding
only
and
accept,
because
there
are
other
things
you
can
add
to
to
this
keyword.
A
I
don't
have
that
announcement,
so
it's
only
you
know
Midway
that
I
get
these
these
announcements
and
they're,
not
that
visible,
and
they
look
like
just
continuation
of
the
description.
So
that's
something
that
we
could
potentially
could
potentially
improve
this
opportunity
to
emphasize
the
availability
status
of
keywords
over
their
contents
and
so
yeah.
This
is
the
biggest
I
think
pain,
Point
here
and
you
then
finally
jump
into
the
preferred
keyword,
rules,
changes
which
is
now
okay,
people
feel
or
I'm
I'm
on
the
right
track.
A
So,
to
recap:
use
browser's,
find
function,
jump
to
First
keyword,
entry
related
to
changes,
read
the
keyword,
explanation
and
then
realize
that
this
keyword
is
deprecated
and
I
need
to
jump
to
the
preferred
keyword
so
I.
Finally,
land
on
this
keyword
and
the
first
paragraph
is
really
good,
because
it
succinctly
describes
the
the
keyword
for
me
and
it's
exactly
what
I'm
looking
for
is
the
one
I'm
debugging
or
that
I
want
to
add
to
my
my
pipeline
and
the
subsections
within
the
keyword,
so
keyword
type
possible
inputs
and
an
example.
A
These
are
great,
they
are
very
visible.
I
can
quickly
jump
to
them
to
find
the
kind
of
content
I'm.
Looking
for
and
read
the
content
that
is
related
to
my
goal
right
now,
so
that
that
is
really
good.
Two
opportunities
here
to
consolidate
and
link
to
how
to
troubleshoot
keywords.
But
that's
that's
a
more
minor
thing
other
than
that.
You
can
see
that
the
user
Journey
here
starts
in
when
finding
a
reference.
Just
neutral
I
can
easily
find
the
reference
page
when
I'm
looking
for
a
keyword,
it
gets
a
little
bit.
A
Frustrating
and
overwhelming
I
then
find
a
keyword,
but
I'm
left
wondering
if
I,
if
this
is
the
right
keyword
or
not,
and
then
realize
no
actually
I
have
to
go
somewhere
else
and
then
finally
yay
it's
the
right
page.
It's
the
right
section
of
the
page
and
it
has
all
of
the
content
and
it's
easy
to
read
so
when
I
get
to
the
right
keyword,
it's
it's
pretty
pretty
nice.
A
So
this
was
the
specific
keyword
scenario.
Now
we're
going
to
look
at
the
use
case,
scenarios
which
is
similar.
It
has
many
things
in
common
which
I'm
going
to
skip,
but
so
this
scenario
instead
of
a
keyword,
we
have
a
use
case.
So
it's
something
that
we
don't
know
exactly
how
to
solve.
So
you
have
a
specific
use
case
of
setting
up
rules
and
conditions
your
pipeline,
but
you're,
not
sure
which
keyword
to
use
you
may
be
migrating
from
another
CI
CD
tool
right.
That
could
be
one
of
the
possibilities
so
again
stages.
A
We
have
find
reference
so
same
thing
as
we
saw
before.
We
then
have
the
look
for
use
case.
So
if,
if
we
look
here
more
closely
at
the
search
results,
if
I
search
for
CI
pipeline
rules
and
conditions,
actually
the
first
result
is
the
best
result
for
what
I'm
looking
for
it's?
Basically
a
page
that
only
talks
about
my
use
case
in
you
know
that
I
want
to
do
with
the
pipeline.
A
So
it's
actually
really
really
good,
but
because
we're
looking
at
the
CI
reference
page
we're
going
to
go
through
the
flow
as
if
someone
picked
the
second
result-
and
you
can
see
the
same
here
in
the
Google
results.
The
first
result
when
I
search
for
this
query,
it's
exactly
the
right
page
for
readers
to
to
go
to
and
then
only
halfway
through
the
Google
search
results.
We
have
the
keyword
reference
page,
but
anyway,
this.
A
That
has
the
the
keyword
and
the
description
and
it
describes
exactly
what
I'm
looking
for
it's,
this
keyword
rules
listed
conditions
to
evaluate
and
determine
the
selected
attributes
of
a
job
and
whether
or
not
it's
created.
So
it's
the
rules
and
conditions
use
case
that
I'm
looking
for
so
yeah.
So
this
is
this
is
pretty
pretty
good,
so
I
jumped
to
the
first
keyword.
Entry
related
to
this
is
wrong:
two
rules
and
yeah.
A
This
is
what
I
want
and
from
here
I
can
read
more
and
dig
into
it
to
find
exactly
what
I'm
looking
for
and
what
I'm
interpreting
the
content.
Reading
the
first
couple
of
paragraphs
that
describes
the
keyword
here
yeah,
it
just
tells
me
what
I'm
looking
for
in
a
very
succinct
way.
So
I
don't
have
to
do
a
lot
of
work
to
understand
if
this
is
what
I'm
looking
for,
so
that
I
really
appreciate
that
in
terms
of
opportunities
also
allow
filtering
the
contents.
A
And
here
it's
a
small
node
regarding
you
know
better
search
engine
optimization,
which
is
a
more
minor
thing
overall.
This
yeah
the
biggest
issue
here
is
just
how
overwhelming
the
page
is
so
as
soon
as
we're
able
to
find
our
way
around
and
land
on
the
specific
keyword
it
just
goes
up,
and
it's
a
very
satisfying
experience
with
all
of
the
information
that
we
need
and
the
final
scenario
is
getting
started.
A
So
this
assumes
that
the
user
is
not
familiar
with
cicd
they're,
just
getting
started
with
their
CI
CD
Journey
they're
learning
the
concepts
they
don't
know
much
about
it,
so
they
land
on
the
reference
to
learn
about
it.
So
it's
one
of
the
most
popular
pages
is
one
of
the
pages
that
turns
up
the
most
in
search
results.
So
this
assumes
that
people
will
land
on
the
CI
reference
page,
even
though
it's
it
is
not
the
most
appropriate
page
for
this
goal
to
get
started
with
gitlab
CI.
A
So
again
we
land
on
this
page,
and
it
is
really
it
can
be
confusing
for
someone
who's
getting
started.
So
we
don't
know
what
this
gitlab
CI
yaml
file
is.
It
just
says,
like
this
document
lists
the
configuration
options
for
your
gitlab
gitlab
CI
yaml
file.
It
doesn't
say
what
it
does,
and
so
I
could
be
a
bit
confused
by
this.
It
has
this
line
on
to
create
your
own
gitlab
CI
file.
A
Try
to
tell
that
demonstrates
a
simple
complex
pipeline,
so
I
might
be
able
to
follow
the
tutorial
if
I
really
really
pay
close
attention
here
on
the
left
side.
There's
this
getting
started
page,
which
is
a
sibling
of
this
keyword,
reference
page
and
that's
exactly
the
page
that
people
should
start
if
they're
getting
just
getting
started,
as
the
name
says,
but
here
I
think
there's
two
things
missing:
it's:
if
I
land
here
and
I,
don't
I,
don't
know
what
this
yaml
file
is.
A
So
if
I
then
decide
to
visit
one
of
these
tutorials,
the
simple
or
complex
pipeline,
if
I
read
the
tutorial
for
a
simple
pipeline,
it's
actually
good,
because
if
I'm
already
familiar
with
basic
CI,
CD
Concepts,
it's
it's
very
helpful
and
I
can
easily
read
it.
If
I'm
not
that
familiar,
this
could
be
a
little
bit
foreign
to
me
because,
as
you
see
here,
you
have
terms
like
pipeline
Runners
jobs.
A
We
have
this
good
part
here
that
when
once
we
get
to
the
steps
it
says,
create
a
gitlab
ciml
file
at
the
root
of
your
repository
and
then
explains
this
file
is
where
you
define
your
CI
CD
jobs.
So
this
is
great
because
it's
in
context
in
the
Practical
tutorial
step,
it
is
describing
very
succinctly
but
in
a
very
useful
way,
with
everything
that
it
needs.
What
this
file
is
all
about.
The
same
thing
it's!
It's
might
be
a
little
bit
more
vague.
A
If
you're
reading
this
line
about
Runners
ensure
you
have
Runners
available
to
run
your
jobs,
you
may
or
may
not
understand
what
what
it
is
depending
again
on
how
familiar
you
are
with
the
basic
CI
CD
Concepts
and
as
we
see
here
at
the
top
highlighted
in
blue.
The
second
paragraph
says:
if
you
are
already
familiar
with
busy
CI
CD
Concepts,
you
can
learn
about
common
keywords
in
the
tutorial
created
complex
pipeline,
so
we
can
go
to
the
complex
pipeline,
but
it's
does
not
go
back
to
the
getting
started.
A
A
A
So
I
think
this
is
a
really
good
page
that
we
should
try
to
link
to
in
a
few
of
these
popular
locations,
and
this
is
it
so
the
the
final
score,
taking
into
account
our
QX
heuristics
was
a
Grade
B,
so
which
is
meets
expectation
but
but
does
not
exceed
user
needs.
So
we
saw
a
few
places
that
we
could,
you
know,
exceed
user
expectations
and
make
the
experience
more
delightful.