(originally developed at: https://docs.divio.com/documentation-system/)
divides into 4 types of documentation:
- Tutorials
- Explanation
- How-to Guides
- Reference
My own documentation got much better when I broke it up along those lines.
1. The new user. They typically know nothing about the product, not even why it exists. The CTO/CIO bought it and now you have to use it. They need lots of hand-holding and needs concrete instruction. Tutorials and explanations are focused on them so they can build accurate mental models of how the software work.
2. The experienced user. They have a pretty good idea of how the product works, but business requirements have changed in some way and know needs to make adjustments to their processes. Or just needs reminders of less used features. Good how-tos and reference material is vital.
If you don't take care of these things the customer will abandon your product sooner than later.
Category is derived from a fairly simple heuristic: whether the content informs action or cognition, and whether the content serves the reader’s application or acquisition of a skill[2]. I’m a fan and it’s simple enough that most anyone can learn it in an afternoon.
Lots of sentences occupying an entire paragraph.
Sometimes ending with "~". Usually (always?) your posts end with a question.
You are clearly using some sort of framework for your posts.
Care to elaborate? ~
> Access to ES6 and ES7 features
> Cross-Platform and Cross-browser Compatibility
Damn, I wasn't aware that since I avoid TS, I cannot use ES6 and ES7, and my vanilla JavaScript doesn't run in all browsers :(
I guess over-hyping the technology that the book is about is to be expected, but it still leaves a slightly sour taste in my mouth when people oversell what they're talking about it.
Don't be like this. Don't spit bile at people because they have different needs and preferences to you.
As I understand it, the TS compiler can translate newer JS features/syntax into backwards-compatible polyfills for you, automatically. I don't really use TS myself, but I'm not going to pretend like that isn't a useful feature.
> since I avoid TS, I cannot use ES6 and ES7, and my vanilla JavaScript doesn't run in all browsers
Where was that claim made? I don't see it in any Typescript docs, or in the book.
You seem to be saying that the TS docs say that these features are unique. They obviously aren't, the documentation is clearly not saying they are, and no reasonable person would say they were.
Transpiling to another platform is a multiplying benefit when combined with other benefits though.
For example: Clojure and Kotlin both target the JVM. The language design of each brings certain benefits. These benefits are clearly more useful if they have a wide deployment base in the form of the JVM.
In the article, you know, linked in this submission, which my original comment quoted verbatim. Again:
> > Some of the benefits of TypeScript:
> > Access to ES6 and ES7 features
I'm saying that these are not "benefits of TypeScript" but benefits of doing transpiling in general with a tool that can "downcast" features like that, which is in no way exclusive to TypeScript nor even began with TypeScript, but AFAIK with Browserify.
When I talk about "benefits of language X" I try to keep it to things that are actually about the language, not particular implementation details also broadly available and used by others, because I feel like it'd be misleading.
A benefit of living in a house is that you don't get wet when it rains. If you didn't live in a house, you might get wet when it rained. But there are other things you could also do to not get wet, such as living in a tent.
It would not be reasonable to say "that's not a benefit of living in a house, because if I lived in a tent, or wore a rain-coat, I would not get wet".
The benefit of "staying dry" belongs to both "a house" and the superclass of "a sheltering structure".
If you defined benefits only on single dimensions, and only allowed them to belonging to level of abstraction at which they are exclusive, then you could argue that no language or technology has any benefit whatesover.
I think most people would think of "benefits of X" as an aggregation of individual specific benefits which may also belong to other aggregations.
I used JS back in the 1990s. Transpiling to JS is a relatively new phenomenon.
No one said transpiling is a TS innovation, nor that it is unique to TS.
> That's why flagging that as something "you get for free, since you added a compiler anyways" feels dishonest. Ultimately it's true, but if that's what you're out after, then adding TS to your project is going way above and beyond just "transpiling new syntax to old syntax".
That's silly. Transpiling is something TS can do, so it's not dishonest to advertise it as something TS can do. If you think TS is too hefty, don't use it. But don't be toxic towards those that do.
You're moving the goalposts to try and defend a bad take. That's how you get brownie points on the Internet for extreme takes, but also how you prevent yourself from learning and growing in the long run. Learn to take an L. You'll be better for it.