51–60 of 71 posts
> Novice writers use big words to hide their own lack of understanding, similar to how novice programmers use frameworks. Maybe another good writing rule is that if you have to cut other people down to get your point across, you might not be as good of a writer as you think.
Stop this. Just stop it. If you're any company worth it's salt with a decent landing page, you're going to need things like internationalization, a contact form, maybe even a light / dark mode if you want to be hipster. How are you going to do form validation? Min / max length of message? Email validation? The list goes on and on... These things become 100x easier with a framework like React.
_Yes_, you can do this all with vanilla JS and HTML. But eventually you're going to make a mess. You don't have to use React either - many choice frameworks can help you with all these things.
My quick two cents about programming and writing is that to be great in either (and not just good), it's far more complicated than just a simple set of rules.
The number one piece of advice: your writing can be clear and structured, but if it's not valuable it's useless and people will stop reading. If you want to write well, figure out who your readers are, figure out what they value, and give it to them.
> You don't need React for your landing page. Stop this. Just stop it. If you're any company worth it's salt with a decent landing page, you're going to need things like internationalization, a contact form, maybe even a light / dark mode if you want to be hipster. How are you going to do form validation? Min / max length of message? Email validation? The list goes on and on... These things become 100x easier with a…
For app front ends I might buy the "Just use React" argument, but that still adds significant complexity, especially for a smaller 2-3 person team trying to get an MVP out the door. I don't think it follows that using a more basic framework like jQuery means you are suddenly accruing technical debt. It really depends on your UX needs greatly.
I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes: When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it…
A lot of the stuff we learned at schools turned out to be bullshit or even harmful.
> You don't need React for your landing page. Stop this. Just stop it. If you're any company worth it's salt with a decent landing page, you're going to need things like internationalization, a contact form, maybe even a light / dark mode if you want to be hipster. How are you going to do form validation? Min / max length of message? Email validation? The list goes on and on... These things become 100x easier with a…
Links to different urls
> a contact form,
Standard html form
> maybe even a light / dark mode if you want to be hipster.
A flip of a single CSS variable.
> How are you going to do form validation? Min / max length of message? Email validation?
``; ``
Don't write for a machine.
I recently did a short training on technical writing. One piece of advice stuck with me because it is a) counter intuitive and b) not followed widely enough. It can also be said to follow "write like you code", so here it goes: When writing a technical document, stick to one word per concept. Say you are using "throughput" for how many requests per seconds a service handles in a given period of time. Don't rename it…
https://en.wikipedia.org/wiki/Elegant_variation
Unfortunately, elegant variation spills over into “non-technical” cases were technical precision is still important, and that becomes a problem — like if you’re whether you’re supposed to know that the Pope is the same as the Bishop of Rome.
[1] Great quote from the article about the absurdities that the practice introduces:
>>A humorist imagined writing a news article about Gaston Defferre: "It's OK to say Defferre once, but not twice. So next you say the Mayor of Marseille. Then, the Minister of Planning. Then, the husband of Edmonde. Then, Gaston. Then, Gastounet and then ... · Well, then you stop talking about him because you don't know what to call him next."
https://www.penguinrandomhouse.com/books/198856/it-was-the-b...
Earlier quoted context omitted.
Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept. Did you mean tech docs as a subset of non-fiction? English is my second language and I always have to think twice translating fiction (into fantasy) and non-fiction (into real).
> Take the word 'non-fiction' next to 'tech docs' as an example of not using one word per concept Good point! I'm guilty of the problem myself. I did mean tech docs as a subset of non-fiction. In these terms, I would now state that technical docs should use 'one term per concept', but that non-fiction doesn't have to as long as some ambiguity is acceptable.