+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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >> wrote: >> > >> > On Thu, Feb 21, 2019 at 5:03 AM Laura Wright <[email protected]> >> 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 <[email protected]> >> 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 :) >> > >> > >> > 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 -- [email protected] >> > To unsubscribe send an email to [email protected] >> > 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/[email protected]/message/37NMYKA7FAUM253IJCKKECX4EOR65QX3/ >> _______________________________________________ >> Devel mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> 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/[email protected]/message/X6BNYYY2CUD5WA3HRY4TNHFF5YYAH4DE/ >> > > > -- > > GREG SHEREMETA > > SENIOR SOFTWARE ENGINEER - TEAM LEAD - RHV UX > > Red Hat NA > > <https://www.redhat.com/> > > [email protected] IRC: gshereme > <https://red.ht/sig> > -- LAURA WRIGHT ASSOCIATE INTERACTION DESIGNER, UXD TEAM Red Hat Massachusetts <https://www.redhat.com/> 314 Littleton Rd [email protected] <https://red.ht/sig>
_______________________________________________ Devel mailing list -- [email protected] To unsubscribe send an email to [email protected] 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/[email protected]/message/BHPEFFGBXKXGCRMXUIVJBCMIVN7MUUPW/
