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
