Great projects have great documentation. Is XCP-ng a great project?
-
Hello to everyone.
There's a very important way to prove to the world that your software is good: excellence in documentation. A project without good documentation is not appealing and looks un-professional.
I mentioned it here or there, but never made a proper announcement, so here it is: we are now using the wiki on our github project to store documentation:
https://github.com/xcp-ng/xcp/wiki
Now, as you can see, it's missing a lot of useful information. Every red link leads to a non-existent page that should exist, and I probably forgot to add many of them. Thankfully, our community comprises many experienced users of XS and XCP-ng, so we should be able to fill the gap.
I'm myself totally unable of writing documentation about storage or networking. My field of expertise is packaging, updates, releases, patching, writing some code. So I only write about what I know. But I'm sure you're not thinking that I will write the documentation alone.
So this is the official start of the "let's improve the documentation together" campaign. Any github user has write access to that wiki (it's versioned so we can revert changes from trolls if needed).
Don't ask for permission before adding or modifying something to the documentation. Just do it, and others will review it.
Even the structure of the home page can be modified. I made one to help us start and see where contributions are needed, but it's just a way to help us start.
Who's in? If you were looking for a way to get involved in XCP-ng but did not know how, here's your chance!
-
Completely agree with you
-
Could someone write the different ways that exist today to get the windows PV tools on XCP-ng 7.5, there: https://github.com/xcp-ng/xcp/wiki/Guest-Tools#windows-guest-tools ?
XOA + windows update (requires locale to be english), use of XenServer's tools ISO, ...
-
@stormi You can attach the ISO from XenServer 7.x to your VM (which you'll obviously have to obtain from either the Citrix site or from a XenServer 7.x install), and then install them from there. Once they're installed, Windows Update should update them accordingly from XOA.
-
@jtbw911 I don't want the answers for myself, but for all those who have no clue how to use them, hence I'm asking for a volunteer to improve the wiki page directly
-
There's been notable progress on the wiki (especially thanks to @borzel), but as you probably guess there's still plenty of room for improvement, including empty pages.
Getting inspiration from XS docs is allowed as long as we do not copy contents from them, because they are copyrighted.
-
I can start adding to this this weekend probably - would a "guide to installing pfsense" be useful? I know there's many guides out there already, but more than half of them have useless (or worse than useless) steps telling people to turn off things that don't need to be turned off
-
Go ahead @fohdeesha
-
@olivierlambert
I don't want to step on any toes here. Would a guide to installing the Community Edition of Xen Orchestra be an appropriate addition to this documentation? -
@Ethan6123 It's already here in the official XO doc: http://xen-orchestra.com/docs/from_the_sources.html
-
I've seen that but to be completely honest it wasn't very helpful to me. I'm talking about more of a step-by-step guide for Linux novices. I would be willing to create one but I don't completely understand the relationship between the XOA team and XCP-ng. I greatly appreciate the XOA team taking this project on and don't want to overstep any bounds.
-
-
@Ethan6123 I'm not sure to really understand. The existing doc is a step by step guide. If you install it from the sources, you need a minimum knowledge, or if you don't want to, you can use XOA Free which doesn't require any knowledge and… it's free!
And finally, you can find on the web multiple 3rd party scripts to install it. Obviously, we cannot guarantee those will work, but if you have issues with those, you can always create issues on their repo!
-
@olivierlambert
Perhaps we are having a miscommunication. Whatever the issue it sounds like additional installation guides for Xen Orchestra Community Edition are not needed at this time. -
@Ethan6123 If you add one in our wiki, we will not delete it
we are too much nerds to not be happy about improving the world (and our documentation)You could write (for example) an overview page that links to the various possibilities.
And I think @olivierlambert is a bit biased because he earns some of his money with XOA licences
and that's all fine! -
Nobody earns money with XOA Free
But otherwise, XOA licenses are what's paying XCP-ng dev right now, yes. Plus paid XOAs aren't meant for individuals/home labs, but for companies, and we'd like to companies get a support/turnkey solution that just work out-of-the-box -
@olivierlambert Well, maybe its a tiny bit easier to sell support if the free documentations isnt top notch
-
@Patrik48 it's not a goal for us to do that. You mainly sell support as in insurance: if you have an issue, you'll have access to the developers of XCP-ng to assist you with a private ticket (and with a fast response time).
This is something you can't have in a reasonable time when you rely only on the community.
-
@olivierlambert I miss things like the manpages for the server, for the commands that is used to build up the answerfile.
Is there a more complete documentations provided for those going for the payed support package?The OP was interested in a step by step guide, thats something that one can write after proper documentation is in place.
Just to be clear, Im fully understand why this isnt a job that we can ask you to do
for us.
I just hopes that someone that is able to read the code can do it, Im just a sysadmin=) -
- Our wiki is open to edition for everyone
- Otherwise, feel free to create a support ticket asking us to write what you need
The main problem is more a priority problem, and obviously, pro support tickets are priority number 1.
