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

[Hans van Kranenburg <hans@knorrie.org>]

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.

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. 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.

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.

Thanks,
Hans

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