4 ms·

>To my astonishment I discovered that I loved to write, even more than I enjoyed writing code. I wish I was this person. I'm one of those (great majority of) p

>To my astonishment I discovered that I loved to write, even more than I enjoyed writing code. I wish I was this person. I'm one of those (great majority of) people whose documentation you'd hate. I deeply hate writing like that because I can never properly explain my tangled thoughts. Even my comments on sites like that are at most few liners. Describing things in code is much easier, since you don't have centuries of context written into words.

user3939382 4y ago
FroshKiller 4y ago
Your class names, variable names, and method names have plenty of centuries' worth of context in them anyway whether you like it or not, not to mention the comments and documentation. I think you'd benefit from looking at writing differently. What you describe--"I can never properly explain my tangled thoughts"--is the essence of composition. The goal of the process of writing is to untangle those thoughts and express them! When I say "process," I don't just mean that you begin typing immediately. Composition is about planning as well. Even if you spend just a few minutes making a list of keywords & important concepts then arrange them on cards in the order you think you should present them in, I bet it would help writing your initial draft of a document. If that doesn't appeal to you, so be it, but look into a composition course, because I genuinely think you could turn something you hate into something that helps. You might never fall in love with writing, but that doesn't mean it can't be a tool that solves problems for you.
rozenmd 4y ago
Just keep writing. It gets better.
- spaetzleesser 4y ago
  From my experience it won't get better unless you put effort into learning how to write. Just writing is not enough.
  - rozenmd 4y ago
    Slight tweak to my original statement: Just keep writing, and get feedback on each piece of writing. It gets better.
mobilene 4y ago
I'm the OP. I wasn't very good at it when I started, but I persisted. And read books on writing. And was edited by a couple of very good editors.
kstenerud 4y ago
It's weird... I was never big on writing, but when I finally tried my hand at a data format specification (https://github.com/kstenerud/concise-encoding https://github.com/kstenerud/concise-encoding), I found that I really enjoyed the experience. It's 3000 lines and took me four years and countless revisions, but I feel it was worth it. I actually enjoyed writing the spec even more than writing the reference implementation :)
- mysterypie 4y ago
  Wow, I like the data format specification you devised. Especially that you insist on "no optional features or extensions" -- something that makes other standards so difficult to rely on. Is there anyone using it? It's always great to have extra ammunition to make a strong case that we should use this instead of, say, XML.
  - kstenerud 4y ago
    It's still in the prerelease stage, but v1 will be released later this year. I'm mostly getting hits from China since they tend to be a lot more worried about security. I expect the rest of the world to catch on to the gaping security holes of JSON and friends in the next few years as the more sophisticated actors start taking advantage of them. For example https://github.com/kstenerud/concise-encoding/blob/master/ce-structure.md#attack-vectors https://github.com/kstenerud/concise-encoding/blob/master/ce... There are still a few things to do: - Update enctool (https://github.com/kstenerud/enctool https://github.com/kstenerud/enctool) to integrate https://cuelang.org https://cuelang.org so that there's at least a command line schema validator for CE. - Update the grammar file (https://github.com/kstenerud/concise-encoding/tree/master/antlrv4-grammar https://github.com/kstenerud/concise-encoding/tree/master/an...) because it's a bit out of date. - Revamp the compliance tests to be themselves written in Concise Encoding (for example https://github.com/kstenerud/go-concise-encoding/blob/master/tests/cte-containers.cte https://github.com/kstenerud/go-concise-encoding/blob/master... but I'll be simplifying the format some more). That way, we can run the same tests on all CE implementations instead of everyone coming up with their own. I'll move the test definitions to their own repo when they're done and then you can just submodule it. I'm thinking that they should look more like: c1 { "type" = { "identifier" = "ce test" "version" = 1 } "tests" = [ { "name" = "Some kind of test" "success" = [ // These must successfully convert to each other { "cte" = "c1 [1 2 3 4]" "cbe" = |u8x 81 01 7a 01 02 03 04 7b| // Events are a kind of text shorthand for what the parsing of cte or cbe should produce "events" = ["v 1" "l" "n 1" "n 2" "n 3" "n 4" "e"] } { ... } ] "failure" = [ // These must fail to decode { "cte" = "c1 100 ]" } { "cbe" = |u8x 81 01 64 7b| } ] } ] }
notjustanymike 4y ago
> I deeply hate writing like that because I can never properly explain my tangled thoughts. I brought a friend of mine to give a couple lectures at our company for this exact reason. He's a professor of non-fiction. There's a couple techniques we learned you can use: - "madman architect carpenter judge" - shitty first draft - The most dangerous writing app, https://www.squibler.io/dangerous-writing-prompt-app https://www.squibler.io/dangerous-writing-prompt-app They're all fundamentally the same concept: write first, edit second.
- Inhibit 4y ago
  I enjoy writing and hate editing! There's always some problem.

user3939382 4y ago

FroshKiller 4y ago

Your class names, variable names, and method names have plenty of centuries' worth of context in them anyway whether you like it or not, not to mention the comments and documentation. I think you'd benefit from looking at writing differently. What you describe--"I can never properly explain my tangled thoughts"--is the essence of composition. The goal of the process of writing is to untangle those thoughts and express them! When I say "process," I don't just mean that you begin typing immediately. Composition is about planning as well. Even if you spend just a few minutes making a list of keywords & important concepts then arrange them on cards in the order you think you should present them in, I bet it would help writing your initial draft of a document. If that doesn't appeal to you, so be it, but look into a composition course, because I genuinely think you could turn something you hate into something that helps. You might never fall in love with writing, but that doesn't mean it can't be a tool that solves problems for you.

rozenmd 4y ago

Just keep writing. It gets better.

spaetzleesser 4y ago
From my experience it won't get better unless you put effort into learning how to write. Just writing is not enough.
- rozenmd 4y ago
  Slight tweak to my original statement: Just keep writing, and get feedback on each piece of writing. It gets better.

mobilene 4y ago

I'm the OP. I wasn't very good at it when I started, but I persisted. And read books on writing. And was edited by a couple of very good editors.

kstenerud 4y ago

It's weird... I was never big on writing, but when I finally tried my hand at a data format specification (https://github.com/kstenerud/concise-encoding https://github.com/kstenerud/concise-encoding), I found that I really enjoyed the experience. It's 3000 lines and took me four years and countless revisions, but I feel it was worth it. I actually enjoyed writing the spec even more than writing the reference implementation :)

mysterypie 4y ago
Wow, I like the data format specification you devised. Especially that you insist on "no optional features or extensions" -- something that makes other standards so difficult to rely on. Is there anyone using it? It's always great to have extra ammunition to make a strong case that we should use this instead of, say, XML.
- kstenerud 4y ago
  It's still in the prerelease stage, but v1 will be released later this year. I'm mostly getting hits from China since they tend to be a lot more worried about security. I expect the rest of the world to catch on to the gaping security holes of JSON and friends in the next few years as the more sophisticated actors start taking advantage of them. For example https://github.com/kstenerud/concise-encoding/blob/master/ce-structure.md#attack-vectors https://github.com/kstenerud/concise-encoding/blob/master/ce... There are still a few things to do: - Update enctool (https://github.com/kstenerud/enctool https://github.com/kstenerud/enctool) to integrate https://cuelang.org https://cuelang.org so that there's at least a command line schema validator for CE. - Update the grammar file (https://github.com/kstenerud/concise-encoding/tree/master/antlrv4-grammar https://github.com/kstenerud/concise-encoding/tree/master/an...) because it's a bit out of date. - Revamp the compliance tests to be themselves written in Concise Encoding (for example https://github.com/kstenerud/go-concise-encoding/blob/master/tests/cte-containers.cte https://github.com/kstenerud/go-concise-encoding/blob/master... but I'll be simplifying the format some more). That way, we can run the same tests on all CE implementations instead of everyone coming up with their own. I'll move the test definitions to their own repo when they're done and then you can just submodule it. I'm thinking that they should look more like: c1 { "type" = { "identifier" = "ce test" "version" = 1 } "tests" = [ { "name" = "Some kind of test" "success" = [ // These must successfully convert to each other { "cte" = "c1 [1 2 3 4]" "cbe" = |u8x 81 01 7a 01 02 03 04 7b| // Events are a kind of text shorthand for what the parsing of cte or cbe should produce "events" = ["v 1" "l" "n 1" "n 2" "n 3" "n 4" "e"] } { ... } ] "failure" = [ // These must fail to decode { "cte" = "c1 100 ]" } { "cbe" = |u8x 81 01 64 7b| } ] } ] }

notjustanymike 4y ago

> I deeply hate writing like that because I can never properly explain my tangled thoughts. I brought a friend of mine to give a couple lectures at our company for this exact reason. He's a professor of non-fiction. There's a couple techniques we learned you can use: - "madman architect carpenter judge" - shitty first draft - The most dangerous writing app, https://www.squibler.io/dangerous-writing-prompt-app https://www.squibler.io/dangerous-writing-prompt-app They're all fundamentally the same concept: write first, edit second.

Inhibit 4y ago
I enjoy writing and hate editing! There's always some problem.