9:57 a.m.
Hi,
TL;DR: please don't direct users to feature pages -- direct them to
end-user documentation instead. And maintain content separation between
end-user documentation and technical docs like feature pages.
...
Lately we've cleaned up documentation on ovirt.org, and I wanted to share
some of my thoughts about it. As a user experience focused person, I really
believe that clear and helpful documentation is crucial to the project's
success. I've also seen outdated documentation be a source of extreme
frustration for our users.
In the distant past, most of oVirt's documentation was written by
developers on a wiki, typically in the form of "feature pages." Feature
pages are basically technical design documents with occasionally some user
help sprinkled in.
With oVirt 4.0, we put a great set of clear documentation, written by
technical writers, on the oVirt website (which was also converted from a
wiki to a regular static site). This documentation is up to date with 4.2,
and we'll get the 4.3 content out there soon.
This official documentation lives at https://ovirt.org/documentation
and it should be considered the authoritative place for users to access our
documentation.
Feature pages, on the other hand, are (now) for developers. When you hear
the term "feature page", think "technical design document." Most
users
should not be interested in this content.
It helps to think about the personas.
1. oVirt admins -- the person who sets up oVirt on Day 1 and 2. This is the
person who cares about and will read the Installation Guide and the
Administration Guide. These live under /documentation, e.g.
https://ovirt.org/documentation/install-guide/Installation_Guide.html
2. oVirt users -- the people who use oVirt to create, manage, and use
virtual machines, etc. This person will care about and read the VM Portal
Guide, User Guides, and such. These also live under /documentation, e.g.
https://ovirt.org/documentation/vmm-guide/Virtual_Machine_Management_Guid...
3. Developers -- you and I, and occasionally highly curious and technical
admins. These people might care about how the project works under the hood
-- high level designs, code flows, etc. Persona 2, oVirt users, do not care
about these details when they are learning to use oVirt, so end-user
documentation should not be polluted with this type of content. This
content now lives exclusively under /develop, the developer's section of
the site.
https://ovirt.org/develop/release-management/features/
Let's help our users by directing them to the end-user documentation, not
to feature pages. If you would like to contribute end-user documentation,
it should go under /documentation and not in a feature page. If you build a
new feature, the technical stuff goes under
/develop/release-management/features/ and the end-user stuff goes under
/documentation.
Feedback welcome :)
Best wishes,
Greg
--
GREG SHEREMETA
SENIOR SOFTWARE ENGINEER - TEAM LEAD - RHV UX
Red Hat NA
<https://www.redhat.com/>
gshereme(a)redhat.com IRC: gshereme
<https://red.ht/sig>