4:57 p.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>
4:02 a.m.
I think from a design perspective we should try to make the features and
documentation pages look more different from one another so users are less
likely to mistake the different types of docs for one another. We can
definitely address this more in the site redesign. I can come up with
further iterations of those pages for the site redesign so we have a couple
different options to talk more about.
I also think from an information architecture perspective we should
probably feature the official end user documentation at a higher level than
the features pages so users would be more likely to find the end user
documentation first and then find the features pages if they dig a
little deeper.
We could also feature different documentation user guides that are more
tailored to the different types of users who might use oVirt.
I'm curious to hear others thoughts on this.
Best,
Laura
On Wed, Feb 20, 2019 at 11:59 PM Greg Sheremeta <gshereme(a)redhat.com> wrote:
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>
_______________________________________________
Devel mailing list -- devel(a)ovirt.org
To unsubscribe send an email to devel-leave(a)ovirt.org
Privacy Statement: https://www.ovirt.org/site/privacy-policy/
oVirt Code of Conduct:
https://www.ovirt.org/community/about/community-guidelines/
List Archives:
https://lists.ovirt.org/archives/list/devel@ovirt.org/message/ZATVWAXBNC6...
--
LAURA WRIGHT
ASSOCIATE INTERACTION DESIGNER, UXD TEAM
Red Hat Massachusetts <https://www.redhat.com/>
314 Littleton Rd
lwright(a)redhat.com
<https://red.ht/sig>
8:24 a.m.
On Thu, Feb 21, 2019 at 5:03 AM Laura Wright <lwright(a)redhat.com> wrote:
I think from a design perspective we should try to make the features
and
documentation pages look more different from one another so users are less
likely to mistake the different types of docs for one another. We can
definitely address this more in the site redesign. I can come up with
further iterations of those pages for the site redesign so we have a couple
different options to talk more about.
I also think from an information architecture perspective we should
probably feature the official end user documentation at a higher level than
the features pages so users would be more likely to find the end user
documentation first and then find the features pages if they dig a
little deeper.
We could also feature different documentation user guides that are more
tailored to the different types of users who might use oVirt.
I'm curious to hear others thoughts on this.
Best,
Laura
On Wed, Feb 20, 2019 at 11:59 PM Greg Sheremeta <gshereme(a)redhat.com>
wrote:
> 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 :)
>
I'd like to add another issue which might be worth discussing now, also
in light of what you suggest re different design. This is: How do we handle
the history of version changes?
Suppose at some version X a new feature is added. We obviously want a
feature page for it (its design) and eventually a doc page for it (perhaps
a few, or only one or a few mentions in existing pages).
Then, at a later version, a new feature is added, which in terms of content
might be worth its own feature page (or not), but is very closely tied to
the first feature. We might have here two quite opposing views:
1. All features have new feature pages, existing feature pages are not
updated once they reach "100% done" state (reality is obviously much more
complex, but let's ignore that for now).
2. Feature pages can and should be updated, and include inline the changes
done per version.
And related to that:
1. Documentation pages are per-version, and are never updated after the
version is obsolete. With each new version we copy (/branch) and create
a new version of the documentation, and update only the latest version,
or simply update in-place (and then rely, in theory, on things like
archive.org, for people that need/want to see documentation for older
versions).
2. Documentation pages reveal the history. When we update them, e.g.
adding a section for a new (sub-)feature, we mention in-line "available
since version X". This is similar to how e.g. python or ansible
documentation
sites look - although they actually do both - both have subtrees per
version and mention in-place - which might be best.
So far, in practice, we did something somewhat similar to (1.), but
it was never an official policy (AFAIK, at least).
I personally tend to prefer both (2.)'s, but less strongly so for the
first one - I can live with many more feature pages, although not sure
is scales well.
Best regards,
--
Didi
9:07 a.m.
Hi,
2. Feature pages can and should be updated, and include inline the
changes
done per version.
This is very hard to enforce as feature pages are part of a different
repository on a different review platform (!). Ideally this kind of
(developer) documentation should be part of source code repository so
you can track history together with the actual source changes. That
way reviewers can also check the changes together.
Martin
On Thu, Feb 21, 2019 at 8:33 AM Yedidyah Bar David <didi(a)redhat.com> wrote:
>
> On Thu, Feb 21, 2019 at 5:03 AM Laura Wright <lwright(a)redhat.com> wrote:
>>
>> I think from a design perspective we should try to make the features and
documentation pages look more different from one another so users are less likely to
mistake the different types of docs for one another. We can definitely address this more
in the site redesign. I can come up with further iterations of those pages for the site
redesign so we have a couple different options to talk more about.
>>
>> I also think from an information architecture perspective we should probably
feature the official end user documentation at a higher level than the features pages so
users would be more likely to find the end user documentation first and then find the
features pages if they dig a little deeper.
>>
>> We could also feature different documentation user guides that are more tailored
to the different types of users who might use oVirt.
>>
>> I'm curious to hear others thoughts on this.
>>
>> Best,
>> Laura
>>
>> On Wed, Feb 20, 2019 at 11:59 PM Greg Sheremeta <gshereme(a)redhat.com>
wrote:
>>>
>>> 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 :)
>
>
> I'd like to add another issue which might be worth discussing now, also
> in light of what you suggest re different design. This is: How do we handle
> the history of version changes?
>
> Suppose at some version X a new feature is added. We obviously want a
> feature page for it (its design) and eventually a doc page for it (perhaps
> a few, or only one or a few mentions in existing pages).
>
> Then, at a later version, a new feature is added, which in terms of content
> might be worth its own feature page (or not), but is very closely tied to
> the first feature. We might have here two quite opposing views:
>
> 1. All features have new feature pages, existing feature pages are not
> updated once they reach "100% done" state (reality is obviously much more
> complex, but let's ignore that for now).
>
2. Feature pages can and should be updated, and include inline the
changes
done per version.
>
> And related to that:
>
> 1. Documentation pages are per-version, and are never updated after the
> version is obsolete. With each new version we copy (/branch) and create
> a new version of the documentation, and update only the latest version,
> or simply update in-place (and then rely, in theory, on things like
> archive.org, for people that need/want to see documentation for older
> versions).
>
> 2. Documentation pages reveal the history. When we update them, e.g.
> adding a section for a new (sub-)feature, we mention in-line "available
> since version X". This is similar to how e.g. python or ansible documentation
> sites look - although they actually do both - both have subtrees per
> version and mention in-place - which might be best.
>
> So far, in practice, we did something somewhat similar to (1.), but
> it was never an official policy (AFAIK, at least).
>
> I personally tend to prefer both (2.)'s, but less strongly so for the
> first one - I can live with many more feature pages, although not sure
> is scales well.
>
> Best regards,
> --
> Didi
> _______________________________________________
> Devel mailing list -- devel(a)ovirt.org
> To unsubscribe send an email to devel-leave(a)ovirt.org
> Privacy Statement: https://www.ovirt.org/site/privacy-policy/
> oVirt Code of Conduct: https://www.ovirt.org/community/about/community-guidelines/
> List Archives:
https://lists.ovirt.org/archives/list/devel@ovirt.org/message/37NMYKA7FAU...
12:36 p.m.
Since almost all of our feature pages are out of date, and always have
been, I wasn't thinking of or planning on trying to keep them updated. (One
more reason to have users avoid them.)
For documentation, though, I would like to have a version selector like
most other projects.
Example: https://docs.okd.io/
On Thu, Feb 21, 2019 at 3:07 AM Martin Sivak <msivak(a)redhat.com> wrote:
Hi,
> 2. Feature pages can and should be updated, and include inline the
changes
> done per version.
This is very hard to enforce as feature pages are part of a different
repository on a different review platform (!). Ideally this kind of
(developer) documentation should be part of source code repository so
you can track history together with the actual source changes. That
way reviewers can also check the changes together.
Martin
On Thu, Feb 21, 2019 at 8:33 AM Yedidyah Bar David <didi(a)redhat.com>
wrote:
>
> On Thu, Feb 21, 2019 at 5:03 AM Laura Wright <lwright(a)redhat.com> wrote:
>>
>> I think from a design perspective we should try to make the features
and documentation pages look more different from one another so users are
less likely to mistake the different types of docs for one another. We can
definitely address this more in the site redesign. I can come up with
further iterations of those pages for the site redesign so we have a couple
different options to talk more about.
>>
>> I also think from an information architecture perspective we should
probably feature the official end user documentation at a higher level than
the features pages so users would be more likely to find the end user
documentation first and then find the features pages if they dig a little
deeper.
>>
>> We could also feature different documentation user guides that are more
tailored to the different types of users who might use oVirt.
>>
>> I'm curious to hear others thoughts on this.
>>
>> Best,
>> Laura
>>
>> On Wed, Feb 20, 2019 at 11:59 PM Greg Sheremeta <gshereme(a)redhat.com>
wrote:
>>>
>>> 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 :)
>
>
> I'd like to add another issue which might be worth discussing now, also
> in light of what you suggest re different design. This is: How do we
handle
> the history of version changes?
>
> Suppose at some version X a new feature is added. We obviously want a
> feature page for it (its design) and eventually a doc page for it
(perhaps
> a few, or only one or a few mentions in existing pages).
>
> Then, at a later version, a new feature is added, which in terms of
content
> might be worth its own feature page (or not), but is very closely tied to
> the first feature. We might have here two quite opposing views:
>
> 1. All features have new feature pages, existing feature pages are not
> updated once they reach "100% done" state (reality is obviously much more
> complex, but let's ignore that for now).
>
> 2. Feature pages can and should be updated, and include inline the
changes
> done per version.
>
> And related to that:
>
> 1. Documentation pages are per-version, and are never updated after the
> version is obsolete. With each new version we copy (/branch) and create
> a new version of the documentation, and update only the latest version,
> or simply update in-place (and then rely, in theory, on things like
> archive.org, for people that need/want to see documentation for older
> versions).
>
> 2. Documentation pages reveal the history. When we update them, e.g.
> adding a section for a new (sub-)feature, we mention in-line "available
> since version X". This is similar to how e.g. python or ansible
documentation
> sites look - although they actually do both - both have subtrees per
> version and mention in-place - which might be best.
>
> So far, in practice, we did something somewhat similar to (1.), but
> it was never an official policy (AFAIK, at least).
>
> I personally tend to prefer both (2.)'s, but less strongly so for the
> first one - I can live with many more feature pages, although not sure
> is scales well.
>
> Best regards,
> --
> Didi
> _______________________________________________
> Devel mailing list -- devel(a)ovirt.org
> To unsubscribe send an email to devel-leave(a)ovirt.org
> Privacy Statement: https://www.ovirt.org/site/privacy-policy/
> oVirt Code of Conduct:
https://www.ovirt.org/community/about/community-guidelines/
> List Archives:
https://lists.ovirt.org/archives/list/devel@ovirt.org/message/37NMYKA7FAU...
_______________________________________________
Devel mailing list -- devel(a)ovirt.org
To unsubscribe send an email to devel-leave(a)ovirt.org
Privacy Statement: https://www.ovirt.org/site/privacy-policy/
oVirt Code of Conduct:
https://www.ovirt.org/community/about/community-guidelines/
List Archives:
https://lists.ovirt.org/archives/list/devel@ovirt.org/message/X6BNYYY2CUD...
--
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>
2:48 p.m.
+1 for a version selector. That would definitely help to make it easier to
navigate through the docs.
On Sat, Feb 23, 2019 at 6:37 AM Greg Sheremeta <gshereme(a)redhat.com> wrote:
Since almost all of our feature pages are out of date, and always
have
been, I wasn't thinking of or planning on trying to keep them updated. (One
more reason to have users avoid them.)
For documentation, though, I would like to have a version selector like
most other projects.
Example: https://docs.okd.io/
On Thu, Feb 21, 2019 at 3:07 AM Martin Sivak <msivak(a)redhat.com> wrote:
> Hi,
>
> > 2. Feature pages can and should be updated, and include inline the
> changes
> > done per version.
>
> This is very hard to enforce as feature pages are part of a different
> repository on a different review platform (!). Ideally this kind of
> (developer) documentation should be part of source code repository so
> you can track history together with the actual source changes. That
> way reviewers can also check the changes together.
>
> Martin
>
> On Thu, Feb 21, 2019 at 8:33 AM Yedidyah Bar David <didi(a)redhat.com>
> wrote:
> >
> > On Thu, Feb 21, 2019 at 5:03 AM Laura Wright <lwright(a)redhat.com>
> wrote:
> >>
> >> I think from a design perspective we should try to make the features
> and documentation pages look more different from one another so users are
> less likely to mistake the different types of docs for one another. We can
> definitely address this more in the site redesign. I can come up with
> further iterations of those pages for the site redesign so we have a couple
> different options to talk more about.
> >>
> >> I also think from an information architecture perspective we should
> probably feature the official end user documentation at a higher level than
> the features pages so users would be more likely to find the end user
> documentation first and then find the features pages if they dig a little
> deeper.
> >>
> >> We could also feature different documentation user guides that are
> more tailored to the different types of users who might use oVirt.
> >>
> >> I'm curious to hear others thoughts on this.
> >>
> >> Best,
> >> Laura
> >>
> >> On Wed, Feb 20, 2019 at 11:59 PM Greg Sheremeta <gshereme(a)redhat.com>
> wrote:
> >>>
> >>> 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 :)
> >
> >
> > I'd like to add another issue which might be worth discussing now, also
> > in light of what you suggest re different design. This is: How do we
> handle
> > the history of version changes?
> >
> > Suppose at some version X a new feature is added. We obviously want a
> > feature page for it (its design) and eventually a doc page for it
> (perhaps
> > a few, or only one or a few mentions in existing pages).
> >
> > Then, at a later version, a new feature is added, which in terms of
> content
> > might be worth its own feature page (or not), but is very closely tied
> to
> > the first feature. We might have here two quite opposing views:
> >
> > 1. All features have new feature pages, existing feature pages are not
> > updated once they reach "100% done" state (reality is obviously much
> more
> > complex, but let's ignore that for now).
> >
> > 2. Feature pages can and should be updated, and include inline the
> changes
> > done per version.
> >
> > And related to that:
> >
> > 1. Documentation pages are per-version, and are never updated after the
> > version is obsolete. With each new version we copy (/branch) and create
> > a new version of the documentation, and update only the latest version,
> > or simply update in-place (and then rely, in theory, on things like
> > archive.org, for people that need/want to see documentation for older
> > versions).
> >
> > 2. Documentation pages reveal the history. When we update them, e.g.
> > adding a section for a new (sub-)feature, we mention in-line "available
> > since version X". This is similar to how e.g. python or ansible
> documentation
> > sites look - although they actually do both - both have subtrees per
> > version and mention in-place - which might be best.
> >
> > So far, in practice, we did something somewhat similar to (1.), but
> > it was never an official policy (AFAIK, at least).
> >
> > I personally tend to prefer both (2.)'s, but less strongly so for the
> > first one - I can live with many more feature pages, although not sure
> > is scales well.
> >
> > Best regards,
> > --
> > Didi
> > _______________________________________________
> > Devel mailing list -- devel(a)ovirt.org
> > To unsubscribe send an email to devel-leave(a)ovirt.org
> > Privacy Statement: https://www.ovirt.org/site/privacy-policy/
> > oVirt Code of Conduct:
> https://www.ovirt.org/community/about/community-guidelines/
> > List Archives:
>
https://lists.ovirt.org/archives/list/devel@ovirt.org/message/37NMYKA7FAU...
> _______________________________________________
> Devel mailing list -- devel(a)ovirt.org
> To unsubscribe send an email to devel-leave(a)ovirt.org
> Privacy Statement: https://www.ovirt.org/site/privacy-policy/
> oVirt Code of Conduct:
> https://www.ovirt.org/community/about/community-guidelines/
> List Archives:
>
https://lists.ovirt.org/archives/list/devel@ovirt.org/message/X6BNYYY2CUD...
>
--
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>
--
LAURA WRIGHT
ASSOCIATE INTERACTION DESIGNER, UXD TEAM
Red Hat Massachusetts <https://www.redhat.com/>
314 Littleton Rd
lwright(a)redhat.com
<https://red.ht/sig>
1884
days inactive
1897
days old
5 comments
4 participants
participants (4)
-
Greg Sheremeta -
Laura Wright -
Martin Sivak -
Yedidyah Bar David