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 <gsher...@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_Guide.html > > 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/> > > gsher...@redhat.com IRC: gshereme > <https://red.ht/sig> > _______________________________________________ > Devel mailing list -- devel@ovirt.org > To unsubscribe send an email to devel-le...@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/ZATVWAXBNC6VYG5WDOFFDMXL32SLUWPI/ > -- LAURA WRIGHT ASSOCIATE INTERACTION DESIGNER, UXD TEAM Red Hat Massachusetts <https://www.redhat.com/> 314 Littleton Rd lwri...@redhat.com <https://red.ht/sig>
_______________________________________________ Devel mailing list -- devel@ovirt.org To unsubscribe send an email to devel-le...@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/QNQZU6MEULBHBJNQVUIZSBMJNIY56GNH/
