Perl 6 - the future is here, just unevenly distributed

IRC log for #crimsonfu, 2017-01-19

crimsonfu - sysadmins who code

| Channels | #crimsonfu index | Today | | Search | Google Search | Plain-Text | summary

All times shown according to UTC.

Time Nick Message
02:48 ilbot3 joined #crimsonfu
02:48 Topic for #crimsonfu is now http://crimsonfu.github.com - ConfiguRatIon Management of Systems Or Network kung FU | logs at http://irclog.perlgeek.de/crimsonfu/today
18:02 hydrajump Looking for opinions on whether including a https://asciinema.org/ terminal session recording is helpful or not in addition to a README tthat includes a set of instructions to accomplish something
18:02 hydrajump or is it just eyecandy
18:04 hydrajump as an example here's a very clear set of instructions https://github.com/kelseyhightower/kubernetes-the-hard-way/blob/master/docs/03-etcd.md
18:05 hydrajump would an asciinema showing those exact steps provide any value?
18:05 larsks hydrajump: an asciinema recording is sometimes helpful because it shows the expected output from everything.
18:07 hydrajump larsks: what if the expected output was included beneath each command in the README?
18:08 larsks Maybe.  I think that clutters up the README a bit, which is why I think it can be nice to have that in an alternate location (like the asciinema recording).
18:08 hydrajump btw the reason I'm asking is for my own projects I'd like to open source at some point. I hate when I come across a project and istructions are bad in that they are lacking steps or just following them doesn't produce the expected results.
18:09 larsks I think if the README file is clear and includes step by step instructions you're fine.  An asciinema recording is "nice", but not requisite.
18:09 larsks It can be super useful when someone says "Hey, this doesn't work", and you can point them at the recording as a demonstration that it does, at least for specific environments :)
18:10 hydrajump yeah that was my feeling as well, but your point about being able to see expected output in an asciinema is a good one
18:10 hydrajump larsks: good point as well
18:10 dotplus I think it's a "different strokes" thing. One more string to your fiddle can't be bad, but I certainly wouldn't consider it a requirement without which your project would generally be considered underdocumented
18:12 hydrajump after all if you go through your own instructions prior to releasing to make sure everything works then might as well record it. I haven't tried asciinema but should be fairly unintrusive
18:16 larsks hydrajump: what you need is something that automatically extracts the commands to run from your README and produces an asciinema recording based on that so that everything is kept in sync...
18:19 littlejohnny joined #crimsonfu
18:19 littlejohnny left #crimsonfu
18:22 hydrajump larsks: I've you seen something like that?
18:28 hydrajump opps s/I've/have
19:11 larsks hydrajump: I wrote something like that myself once, but that was a while ago.  There's the doctest stuff for python, but that's language specific (neat, though)
23:00 pdurbin hydrajump: maybe you can have some of us try the steps in your readme to see if they're clear enough. What's your project about?

| Channels | #crimsonfu index | Today | | Search | Google Search | Plain-Text | summary

crimsonfu - sysadmins who code