Changes for "Getting Started cli"
Closed this issue · 2 comments
Context:
https://linuxcontainers.org/lxd/getting-started-cli/
https://discuss.linuxcontainers.org/t/proposed-additions-and-changes-for-getting-started/7804
https://discuss.linuxcontainers.org/t/request-add-more-info-about-images-into-getting-started/7738
Todo:
Technical:
- TOC (Table of Content)
- Admonitions
- Footnotes
- Attribution Lists (use specific html classes)
- FencedCode
- [blocked] other style for tables (reduced width, vertical borders) (also see: #420)
Content:
- Initial Configuration
- VM's [1]
- Launch Instances [1]
- Images [1]
- Links [1]
Moved Profiles
and Tips&Tricks
to the Advanced Guide (#413).
[1]: see pull request #433
Note: This is of course not urgent, but because I haven't received an answer in the forum, I wanted to post it here, so it would not be forgotten 🙂 .
I would like to change some things in the "getting started-doc", but before I start to write a pull request for it, I would appreciate to get some answers (so I (and maybe others) know what you want to see included and what not):
- Regarding general questions for editing (what is allowed etc.):
- can I add links to external websites, like:
- official external documentation, e.g. cloud-init?
- blogs like simos blog: https://blog.simos.info/tag/lxd/ (only at the bottom, for "useful links" (or similar)) ?
- I guess everything should be as short as possible?
- Regarding my ideas for changes;
I would add more info about:
-
the options of
lxd-init
(like answers to "what is clustering?") -
VMs:
should I seperate the vm-part from the container-part or mingle it (most topics like images, profiles etc. apply to both)? -
details for "lxc launch" (like requested in this issue)
-
profiles (only short info + links)
- extended info could be in the docs (https://linuxcontainers.org/lxd/docs/master/profiles), but would need a rewrite
-
(maybe later) cloud-init (only short info + links):
- extended info could be in the docs ("cloud-init", but would need a rewrite
- potencial link: https://cloudinit.readthedocs.io/en/latest/topics/examples.html
-
images:
- "official" images (how to list, find and use them)
- "download the images yourself"
- maybe only a link to seperate documentation (would need a new page, maybe "images")
- otherwise link to imageserver and how to download & import the images
- "building your own images":
- maybe only a link to seperate documentation ("images"), otherwise:
- link to distrobuilder instructions
- link to image templates
- extended info: e.g. about how to modify the image templates
- maybe only a link to seperate documentation ("images"), otherwise:
- link to image handling or include it in new document ("images")
-
storage (pools) (only short info + links)
2.a) I would also like to add:
- a section for tips & tricks (for better workflow)
- (useful) links:
-
To the documentation and also:
-
To the forum: https://discuss.linuxcontainers.org/
-
- Regarding the layout of the document (what kind of layout/style do you prefer?);
I would like to:
-
add a Content-List at the beginning (so one can easier find content inside);
I created an example here: https://github.com/toby63/linuxcontainers.org/blob/master/content/lxd/getting-started-cli.md#content -
use tables to summarize flags, commands etc., I also created one example in the section about snap packages:
https://github.com/toby63/linuxcontainers.org/blob/master/content/lxd/getting-started-cli.md#snap-package-arch-linux-debian-fedora-opensuse-and-ubuntu
-
Yeah, external links are fine. For the tutorials, we may want to link to the tutorial section on the forum instead where @simos is posting links to the tutorials and other content. Eventually I'd like to have all the posts there automatically linked directly from the website, but that will take a bunch of python code which I don't have time to write right now.
-
For consistency with help and doc, you should use
instances
for anything that applies to both containers and VMs and just highlight some of the little differences when it matters, that should avoid a lot of duplication.
All sounds good. For tables, I'm not sure whether the markdown setup we have in the website generator knows how to handle those. It may be an easy change to make them work though.
In any case, it's great that you want to work on this stuff. Our website does need quite a bit of updating but we've been struggling to get some time to do it... I'd recommend setting up a working environment on your machine where you can generate and access the updated website, then send many smaller PRs rather than one large one.
It's easier for us to review and also means changes go live faster. It also lets @tenforward and others translate things as they change rather than get one massive change that may take a while to translate.