Hey folks. I'm sharing a guide I wrote mostly as a form of self documentation or "Blogumentation", a word I've recently come across and liked. I've never had a blog before, as I've never felt I...
Hey folks.
I'm sharing a guide I wrote mostly as a form of self documentation or "Blogumentation", a word I've recently come across and liked.
I've never had a blog before, as I've never felt I had much reason to keep one. But writing more is one of my themes this year, and so, now I have one.
I'd be really keen to hear feedback on any of: my writing style; the technical content of the post; or even the site itself, which is generated with the software I'm writing about (the dreaded "build a static site generator and then write about the process" trope).
I feel a little bit ick about posting a link to my own site here, but it seems to fall within the guidelines and I don't know how else I'd find anyone to read it other than share it on forums I frequent.
I like the way the topic was approached overall, with emphasis on the why before going into detail. I think all the plain language explanations were pretty good. The Server-Sent Events Broker part...
I like the way the topic was approached overall, with emphasis on the why before going into detail. I think all the plain language explanations were pretty good.
The Server-Sent Events Broker part was pretty dense though, and where my eyes started to glaze over a bit. I think it's a difficult post since it has two audiences: people trying to implement their own similar system and who work with Go; and then curious passersby like me. The code and detailed explanations are helpful for the first audience, but slow down reading for the second audience.
I'm not sure if the best way to do it for this blog and whoever the intended audience may be, but: I guess I'd make sure everything's digestible in plain language when removing all the source code from the post. Then once that is easy to read, add the code (or the most important snippets) back. Maybe move the full code to an appendix?
Thanks talklittle, this was exactly the kind of feedback I was hoping to receive. I really like your suggested approach of writing in plain English without code, before adding examples back in. I...
Thanks talklittle, this was exactly the kind of feedback I was hoping to receive.
I really like your suggested approach of writing in plain English without code, before adding examples back in. I might even take that slightly further and have the code snippets collapsed, or condensed with the option to expand for those interested.
I have a link to the full code in a repository at the end. Are you suggesting it might be better to have the full code written directly into an appendix?
Hey folks.
I'm sharing a guide I wrote mostly as a form of self documentation or "Blogumentation", a word I've recently come across and liked.
I've never had a blog before, as I've never felt I had much reason to keep one. But writing more is one of my themes this year, and so, now I have one.
I'd be really keen to hear feedback on any of: my writing style; the technical content of the post; or even the site itself, which is generated with the software I'm writing about (the dreaded "build a static site generator and then write about the process" trope).
I feel a little bit ick about posting a link to my own site here, but it seems to fall within the guidelines and I don't know how else I'd find anyone to read it other than share it on forums I frequent.
I like the way the topic was approached overall, with emphasis on the why before going into detail. I think all the plain language explanations were pretty good.
The Server-Sent Events Broker part was pretty dense though, and where my eyes started to glaze over a bit. I think it's a difficult post since it has two audiences: people trying to implement their own similar system and who work with Go; and then curious passersby like me. The code and detailed explanations are helpful for the first audience, but slow down reading for the second audience.
I'm not sure if the best way to do it for this blog and whoever the intended audience may be, but: I guess I'd make sure everything's digestible in plain language when removing all the source code from the post. Then once that is easy to read, add the code (or the most important snippets) back. Maybe move the full code to an appendix?
Thanks talklittle, this was exactly the kind of feedback I was hoping to receive.
I really like your suggested approach of writing in plain English without code, before adding examples back in. I might even take that slightly further and have the code snippets collapsed, or condensed with the option to expand for those interested.
I have a link to the full code in a repository at the end. Are you suggesting it might be better to have the full code written directly into an appendix?