robszumski
commented
9 years ago This is good feedback. The document could have better hierarchy and flow. We're very constrained on technical writing resources...I've thrown the "help wanted" label on this.
I'd be happy to give feedback and suggestions to someone if they opened a PR. Since the entire topic is about general confusion, I'd love to see how a community member would describe the process, the terms that they would use, etc. Otherwise, we'll try to get to this in the future.
pop
Summary:
User entered IRC channel and politely insisted that the documentation for bare-metal install of CoreOS was poor (especially for non-specialists) and needed to be fixed... New users to CoreOS (but with 5-10+ years of linux experience or more) are having trouble with the documentation, so probably more so than they should. Multiple users have brought this specific issue up, including a blog post which is dedicated to this subject entirely.
http://stevieholdway.tumblr.com/post/90167512059/coreos-bare-metal-iso-install-tutorial
Possible Resolution
Solution would be to add a Bare Metal Install Doc and/or Update General CoreOS documentation for clarity to a brand new user who needs results oriented approach rather than a system architecture overview.
User Request from IRC:
[12:59:55] any of the devs or documentors on here right now?
[13:01:37] Even if not they frequently read backscroll. Might just want to ask your question...
[13:03:43] okay. not as much a question as just something i found. A few weeks ago i was in here trying to get setup help on a bare metal install. i had mentiond how confusing the documentation was and it seemed i was alone in this thought and after several weeks of trying to figure out unsucessfully how to install core and actually be able to use it (i cant even count how many times i reinstalled trying to get it right) i stumbled across this blog post and
[13:04:50] it eloquently outlines all the issues i had with the flow of the docs and explains why those of us who are not well versed in this get so easily confused. and its explained much better than i could pu ti
[13:04:54] circ-user-nZ7mw:
http://stevieholdway.tumblr.com/post/90167512059/coreos-bare-metal-iso-install-tutorial
[13:05:39] <circ-user-nZ7mw: perhaps one of the doc writers or devs could take this into account and use it to make a noobs guide to install
[13:09:58] <circ-user-nZ7mw: the one thing too that was the most invaluable information in that post is that if you screw up, you can modify the config file in /var/lib/coreos-install/user_data from live cd and reboot into the system aghain so you dont have to do the install over and over and over and over like i did.
[13:15:00] <bitshark: if your still here.. im not a formal dev or documentor but i do have a github issue i opened , and ive commented on a few threads, read the docuemtnation, etc
[13:16:21] <bitshark: i'll open up a github issue to update the documentation per user request
[13:22:30] <circ-user-nZ7mw: yeah thank you. its just so frustrating to me. ive been trying for 2 weeks to get this going. ive been admining linux systems since i was 14 and youd think id have a handle on this being 24 now lol but this system just had me stumped to no end. i was getting ready to just give up and build a HA CLuster with Cent or node with HAProxy balancers in front of them unti li found this article.
[13:22:53] <circ-user-nZ7mw: *cent or ubuntu with node
[13:23:17] <circ-user-nZ7mw: its not that they are bad [13:23:19] <circ-user-nZ7mw: pewr say [13:23:22] <circ-user-nZ7mw: *per
[13:23:38] <circ-user-nZ7mw: its just way too much info and its not well presented
[13:24:07] <circ-user-nZ7mw: the quickstart guide is anything but quick it gives you the bare bones to a system you cannot log into.
[13:24:30] <circ-user-nZ7mw: nor any info as to why you cant log into it. [13:24:45] <circ-user-nZ7mw: and so you reinstall twaking some stuff and it still doesnt work.
[13:24:59] <circ-user-nZ7mw: the digitalocean tutorial on it was fairly helpful but still not fully applicable
[13:25:18] <bitshark: today i JUST got around to CoreOS [13:25:26] <bitshark: when you came in the channel i was booting vmware to try out CoreOS [13:25:47] <bitshark: so this actually might be good, b/c i can document what i'm doing and maybe update the docs [13:25:53] <bitshark: without alot of extra effort
[13:25:58] <circ-user-nZ7mw: oh dont get me wrong. i m loving core. the idea is perfect. it take high availability to a WHOLE new level and never having worked with etcd/systemd like this before, never using a cloud configbefore this is unchartyed territory for me and i have been having trouble wrapping my head around it.
[13:27:53] <bitshark: circ: if you could suggest like 3 top changes to it , what would they be [13:28:03] <bitshark: to the docs to make them suck less hard
[13:29:54] <circ-user-nZ7mw: nor i just mentioning my struggle. and the devs and experience guys in here often talk about things like its as easy as breathing and it doesnt totally help which is why i said a noobs guide. even if youve been running linux a long time, your a noob to any tech new to you. which is what this is. its just way too much information too fast. the quickstart guide in my opinion should have a few basic things in the preamble, stable beta alpha, it shou
[13:30:29] <circ-user-nZ7mw: the way they are now is misleading [13:30:49] <circ-user-nZ7mw: generally you follow steps in a tutorial and the quckstart begins at M instead of A [13:31:22] <circ-user-nZ7mw: it gives you an install command that doesnt work (no cloud config) so once you get a system installed and move on to the next step you find out that command doesnt do diddle
[13:31:37] <circ-user-nZ7mw: you now need to do the same comand with a cloud config
[13:32:47] <circ-user-nZ7mw: and the cloud config it gives you as a tutorial is incomplete
[13:32:54] <circ-user-nZ7mw: so it too doesnt work
Okay so that's all for now. Will add more information if I receive it.