Re: [Xen-devel] [PATCH] docs/sphinx: Introduction

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 07/08/2019 23:49, Hans van Kranenburg wrote:
> Hi, (dropped most of the Cc:)
>
> On 8/7/19 9:41 PM, Andrew Cooper wrote:
>> Put together an introduction page for the Sphinx/RST docs, along with a
>> glossary which will accumulate over time.
>> [...]
> I've been using Xen for 13+ years now, so I'm not really able to provide
> feedback about how someone new to it would experience things.
>
> But, I think there's some feedback I can provide.
>
> The first page, admin-guide/introduction is very well written, it's
> short and it sets a very good frame of reference. Keep it like this.

I think there are a few other things it should cover.  A very brief
history of Xen's major milestones, but I was planning to keep that to a
paragraph of two.  (When Xen started, PV guests being modified to know
about Xen, HVM guests with hardware virt so we could run windows, then
expanding into ARM + hardware virt).

> When writing documentation, you're not only providing information. You
> can "steer" a lot of things. By consciously deciding about the exact
> technical level of stuff that you provide on the "front page", you'll
> automatically cause a selection of audience that you want to stay or
> want to browse/scare away because it's not for them.
>
> And, I think this first introduction page exactly does that, but I this
> is where I'm of course biased.

"does exactly that" => you mean scare people away? :)

Yes - getting the right level of detail here is critical, and is going
to need outside feedback.

> I think it will "work" for a new user who
> already knows what a NIC and a Kernel is, and it will work for an
> interested developer, looking to help figuring out to get it running on
> $whatever hardware not fully supported.
>
> The other pages already available seem to be developer documentation
> instead of user documentation.

It is a random mix of small tasks which I've managed to get done in my
distinctly negative free time.

The focus is first and foremost on high-quality documentation, and I am
fully expecting to have to shuffle the exact structure and layout as it
gains more content and it is easier to spot where the logical divisions lie.

For now, the paragraphs on the front page are my best guestimate of how
to structure it, but they are by no means set in stone.

> One of the things on my wishlist is to help cleaning up the end user
> documentation for Xen. Xen itself has a wiki with a lot of horrible
> outdated information, there's a Debian wiki with even more horrible
> outated information, and so on. As a new user, you completely get lost
> because you have no idea what's still relevant or not. It's a shame that
> we lose potential new users for which the product would be a good fit
> because of that.
>
> (With a group of motivated people, a few with technical knowledge and a
> few with decent tech. writer skills we could do a "sprint" getting some
> big hammers and chainsaws out to do some huge spring cleaning and
> restructure it.) A wiki is a great solution for short-term low-barrier
> gathering of information by anyone, but in the long term it's just a big
> accumulation of cruft without a clear maintainer.
>
> Instead of fully starting to hijack this thread now, my last feedback
> would be: in your git commit message, you don't mention what your target
> audience is. I'm interested to hear what it is.

This page is aimed at people who have no knowledge of Xen.  I don't
expect people who routinely work on Xen to read it more than once.

However, I also don't think that here is an appropriate place to cover
"my first introduction to a computer".  If we were to aim at that level,
noone would read it - its too high level for anyone who knows what a
kernel is, and Xen is far too niche for anyone who doesn't know what a
kernel is to find.

Again, I would welcome feedback here on exactly what level we should aim
"my first introduction to Xen" at.

As for the longterm goal of the docs, I do stand by my initial guestimate.

1) The admin guide for people who aren't programmers but want to run a
Xen system.
2) The guest guide for people wanting to develop against our ABI/APIs.
3) The developer guide for people hacking on the content of xen.git

2 and 3 have a fair overlap, but I think it is important to keep them
distinct.  2 will include things like hypercall and library API/ABI
references, whereas 3 is the only place I'd expect to see information on
how Xen does memory management, or breakdowns of how the boot paths
work, etc.

As I said - everything is subject to improvement as the content grows. 
I care far more that we end up with high quality, coherent
documentation, than it ending up looking exactly as I predicted at some
point in the past.

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel