When reading succinct technical documentation, I see how so many times the documentation attempts to cover everything possible. ~
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? ~
The thing is, documentation isn't a monolithic thing --- it really needs to be sub-divided/categorized into subsets which are useful to specific categories of folks working on, or working with, a project:
That does make a huge difference, though I have found you also need to divide by the audiences. There are usually two main audiences that need addressing:
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.
Agreed, but IMHO it should be layered so one can enter at the highest conceptual level and drill down and back up so there's a continuous flow of understanding.
My experience is that if there's too much documentation for a given representation, a not insignificant number of folks will not read it --- divide and conquer seems to be a workable approach.
What you describe sounds a lot like Diátaxis[1], which is a strategy for writing and organizing technical documentation. It categorizes docs into one of four categories: tutorials, explanations, how-tos, and references.
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.
you're not meant to scroll ahead, the intention is to create a time sink in each chapter. I figured this out after reading the first chapter forever, then I was like "wait a second this is the concise book? how can I read the introduction forever?"
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?
Determining the motivation for design decisions is outside the scope of what any external party can and/or should do. The most the author could do is echo what's in the docs (if present), or give their own guess on why things are the way they are.
Please provide a PDF as well. I cannot read books in HTML format because I need to keep track of where i left. That means I either have to leave the browser tab open (but this is prone to accidentally closing it) or I need to bookmark every progress, which creates noise in my bookmarks. With a PDF I simply leave it, the reader remembers my last page. I also have a sense of progress with pdf.
I love the Typescript handbook, but wanted the examples to be "runnable". It turns out that the TypeScript compiler runs pretty fast in the browser for trivial code snippets, so I threw together https://ts.coach (TypeScript handbook with code examples that execute in the browser + instant type checking)
Thank you for the excellent feedback. I had this realization a while back that I'm a mobile user during "consumption" (e.g. browsing HN late at night), but a desktop user for "production" - now I see how it applies to this side project as well. Also, I still need to figure out some React performance issues which make it virtually unusable on pre-2020 machines :(
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.
I show people coming from object oriented backgrounds this page first in order to correct the perception that TypeScript is best used with that programming paradigm.
> I show people coming from object oriented backgrounds this page first in order to correct the perception that TypeScript is best used with that programming paradigm.
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.
To clarify, I’m not claiming that classes have no place in Typescript. What I’m saying is that many people coming from OOP backgrounds tend to have the mistaken belief that TypeScript is best written with that paradigm. While it can be in some cases, it should not be assumed to be the best way. In fact, the documentation linked above asserts that “free functions over data” are extremely powerful, and “tend to be the preferred model for writing programs in JavaScript.”
I don't know, the number of people that know what a mapped or sum types are is strikingly low, let alone some of the more advanced concepts or even tsconfig.
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.
I know why typescript "succeeded", but always wonder what kind of web we would have if infact Haxe had become more popular for web in the early days. My guesstimate is we would have had bundlers in native code much, much earlier, and generally much faster and more robust tooling. Its only now we see projects like esbuild, and even TS being written in a compiled language (go), and other efforts in rust.
Also it would have been interesting sto ser what influence Haxe would have had on javascript itself
Thats true, but comes with a cost. TS has become an incredibly complex language, even it only provides types. Thats being said is will always lack features as it only "javascript".
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.
Yes, amazing language - I recall having a look at it in 2013 when I was scrambling for a replacement for Flash (also amazing platform). Shame it doesn't solve the problem at hand.
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.
> For the same reason ReasonML took years to overtake fartscroll.js in the number of stars on GitHub.
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!
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.
I think the point is that you can write your code using ES6 and ES7 and the TypeScript compiler allows you to output ES6 or ES5 compatible code if you want to make sure it runs in older browsers as well. You can do that with non-TypeScript ES code as well but you’re bound to use another transpiler. With TypeScript you get it „for free“ since you need to compile your code either way.
Ah yeah, kind of like how I get a drink for free if I get the hamburger menu, even if it costs more? Kind of weird perspective, but I can accept that it's something zealots tell themselves so "we're doing it differently" actually computes for them.
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? ~
https://diataxis.fr/
(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.
1. https://diataxis.fr/
2. https://diataxis.fr/compass/
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://nemorize.com/roadmaps/typescript
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'.
https://www.typescriptlang.org/docs/handbook/intro.html
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!
[0]: https://theonion.github.io/fartscroll.js/
> 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.