[ovirt-devel] Re: oVirt documentation vs. feature pages

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&gt; 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&gt; > wrote: > > > > On Thu, Feb 21, 2019 at 5:03 AM Laura Wright <lwright(a)redhat.com&gt; > 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&gt; > 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>