Most developers want guidance instead of exhaustive details. Developers want to know where they should focus their time and where they can afford to skim over the documentation. And they want to know where they should expect to encounter problems and difficulties.
A simple framework to use when producing succinct technical documentation is to divide the documentation into three sections.
Maps: Identify what type of problems this documentation can assist you with
Defaults: Understand what the majority of people will experience and what to do about it.
Exceptions: Identify when to deviate from the default recommendations.
Succinct documentation does an excellent job of providing clarity by eliminating edge cases. The more clearly the user understands the documentation the more useful the documentation will be during the time where the user is experiencing the most confusion.
The danger is the temptation to simplify the information contained within the documentation to such an extent that the user is left with a large amount of missing information and no method for seeking assistance with incomplete information.
What situations have you encountered where the information contained within short technical documentation has been more helpful than official technical documentation? ~
(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? ~
https://gibbok.github.io/typescript-book/book/differences-be...
So we know there are types and interfaces. One support declaration merging, one does not. Both can extend others, but in different ways. But why? Why there are two of them? When should I use them? Is one better than the other?
To the author, congrats and thank you. I have one piece of feedback:
When you are typing Typescript on your keyboard you are typing types using a strongly typed language.
Some definitions would be useful to novices: 'type' as a noun or verb, in the mathematical context + the notion of 'strong'.
This comment actually invigorated me to try the site from my phone and improve the experience, so I sincerely thank you for the motivation.
I've considered doing a similar project to yours writing or using some mobile friendly editor and hooking it directly into TypeScript's LSP, which can be easily added to a web page, but was never motivated/disciplined enough to push through it.
It should be your first resource when looking something up, it's usually quite clear and often helpful, but I find it somewhat confusingly organized and rather incomplete. It's more of a reference than a tutorial or guidebook, per se.
https://www.typescriptlang.org/docs/handbook/typescript-in-5...
I think you're confusing things. Languages like Java or C# impose an artificial constraint that free functions don't exist and functions can only exist as members of a class. You don't see this constraint in OO languages such as C++.
Also, it's a simplistic assertions to claim that classes have no place in TypeScript or aren't idiomatic. That's just nonsense based on specious reasoning. Classes/objects with function members are still the best way to implement some features. I'm seeing too many people writing absurd typescript code who go through great lengths to avoid a class because they think a class is taboo. They pull out convoluted stunts like passing closures as object members, just to avoid the sin of rolling out a class.
I've always thought that typescript is in the real of technologies that developers use for years but never really master such as css. Maybe not as severe as css, but it's the same direction.
Also it would have been interesting sto ser what influence Haxe would have had on javascript itself
The creators of TypeScript realized early on that people don't need yet another ecosystem, but a migration path that won't pause development.
Haxe has a more robust, but simpler typesystem, that comes from ocaml.
Haxe also compiles to C++ so making native tools would have been a breeze.
TS sits at the top chair, but there is many "better" options out there, like Elm (even its kild of a dead languge) and ReScript/ReasonML etc.
TS is good, but will never be a perfect language for javascript. It will always be a mediocre option, that is growing more and more complex in every new release.
Hardly anyone cares TypeScript isn't perfect when they can migrate their (or anyone else's) terrible, but business-critial JS library to TS and continue development without skipping a beat.
For the same reason ReasonML took years to overtake fartscroll.js in the number of stars on GitHub.
A huge part of TS's complexity is there so that library authors can describe some exotic behaviours seen normally only in dynamically-typed languages. When you're writing an app you don't need the vast majority of those features. Personally I regret every usage of `infer` in application code.
Wow, that's a fascinating statistic! Certainly puts the popularity delta into a different light.
On a separate note, the fartscroll.js demo page[0] no longer works since code.onion.com is no longer accessible. Truly disappointing. Luckily their release zip contains an example.html!
> 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.