search

xcp-ng / xcp-ng-org

XCP-ng org website
69 stars 92 forks source link

Update install-xcp-ng.md #266

Open kevemueller opened 5 months ago

kevemueller commented 5 months ago

Added section on advanced installer parameters.

Before submitting the pull request, you must agree with the following statements by checking both boxes with a 'x'.

  • [x] "I accept that my contribution is placed under the CC BY-SA 2.0 license [1]."
  • [x] "My contribution complies with the Developer Certificate of Origin [2]."

[1] https://creativecommons.org/licenses/by-sa/2.0/ [2] https://docs.xcp-ng.org/project/contributing/#developer-certificate-of-origin-dco

stormi commented 5 months ago

Thanks for your contribution! This looks useful but needs to be also reviewed against existing docs in https://github.com/xcp-ng/host-installer/blob/master/doc/ and raises questions about duplication of information where one may become obsolete while the other is updated.

Also, I wouldn't list deprecated items.

kevemueller commented 5 months ago

Hi Stormi, this information was necessary for me to get xcp-ng installed in the first place (network_device is a must if you have multiple cards). It is not obvious where to look for it if you are on the xcp-ng site. Indeed I have found host-installer documentation and used it as a guideline. IMO this information must be easily accessible directly from the xcp-ng installation page. The txt file in the repo may as well be removed in favour of the clear and up-to-date information on the web. As for deprecated options, I would mark them deprecated, but still list them. I don't have the history to tell which is deprecated and the code would not tell me.

Happy to review, resubmit based on specific feedback.

ydirson commented 5 months ago

What about just linking to https://github.com/xcp-ng/host-installer/blob/master/doc/parameters.txt instead, and submit improvements as patches to the official doc? Maybe we should setup a 8.2 ref in there so we could separately link to the docs pertaining to each release, BTW. We could also consider submitting patches upstream to make those docs proper Markdown for better reading.

kevemueller commented 5 months ago

Hi Yann, the place of this file is not easy to find, especially if you do not know of its existence. The information in it is valuable for anyone browsing https://docs.xcp-ng.org/ so that is the primary place I would expect it to be. As a newcomer to xcp-ng you just read its documentation, and if something is not there, you just expect it not to exist.

You have there in the appendix a reference for the answerfile and a reference for xe. The crucial missing first piece in the chain, the reference for the boot parameters would fit there very well. Neither of these two appendices are "authoritative" either, but they are there for a good reason.

Feel free to close this as not mergeable if you disagree.

olivierlambert commented 5 months ago

I think the Appendix section could be a right fit for it. In theory with Docusaurus, we could have "namespace" for each release, but just for this extra content, I don't think it's a big deal.

About duplicating the content, I agree it's suboptimal, but @kevemueller has a fair point about discoverability.

ydirson commented 5 months ago

I think the Appendix section could be a right fit for it. In theory with Docusaurus, we could have "namespace" for each release, but just for this extra content, I don't think it's a big deal.

This is actually a place where some content actually changes from 8.2 to 8.3, some options removed (due to removal of DOS disklabel) and some added (control over *gpgcheck). And more could come from our pending PRs.

About duplicating the content, I agree it's suboptimal, but @kevemueller has a fair point about discoverability.

I'd think linking to the content would address the discoverability issue?

olivierlambert commented 5 months ago

You won't be able to use the search, parsing for arguments (since the text is parsed by Algolia). That's why I'm talking about discoverability :)

ydirson commented 5 months ago

You won't be able to use the search, parsing for arguments (since the text is parsed by Algolia). That's why I'm talking about discoverability :)

Ah, what we need is rather an include mechanism, then!

olivierlambert commented 5 months ago

I don't think it's possible sadly (or not easily). I prefer to keep people inside our doc than having to browser all around, at least a dedicated page with various examples (the most common things to use) and a link to the complete documentation will probably be a lot better than just a link provided somewhere. That could be a good intermediate solution.