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.
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.
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 :)
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.
There are still a few things to do:
- Update enctool (https://github.com/kstenerud/enctool) to integrate 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/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... 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|
}
]
}
]
}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
They're all fundamentally the same concept: write first, edit second.
Just keep writing, and get feedback on each piece of writing. It gets better.