loading words...

Mar 02, 2019 17:38:06

How not to write programming documentation

by @valentino | 238 words | 64🔥 | 362💌

Valentino Urbano

Current day streak: 64🔥
Total posts: 362💌
Total words: 172646 (690 pages 📄)

Most of the times documentation is of acceptable quality. It is rare to find really good documentation online, but it is also rare to find a really abysmal one. We have reached a middle ground which is great, I still hope that in the future the situation keeps improving.

Observables in Rx:

Rx.Observable.prototype.flatMapLatest(selector, [thisArg])

Projects each element of an observable sequence into a new sequence of observable sequences by incorporating the element's index and then transforms an observable sequence of observable sequences into an observable sequence producing values only from the most recent observable sequence.

If you didn't understand a single word don't worry. I did not either.

That's what you end up writing if you think everyone has your own level of knowledge of a subject. Jargon that can only be understood by someone that already knows the topic you're talking about.

If you're writing a guide or any piece of documentation you need to assume that the reader has no prior knowledge of the subject at all, unless you know for a fact that you are writing for an already experienced audience.

If you find yourself writing for an already experienced audience make sure to write a disclaimer before the main body of the article stating that prior knowledge of the topic is required.

Once you learn something it feels easy, but when you were learning it did not feel that easy. Never forget that.

Originally published at www.valentinourbano.com

  • 1

    @valentino
    congratulations on hitting 100!!!
    they say better late than never
    but actually 101 is way cooler :D

    Lucjah avatar Lucjah | Mar 02, 2019 17:46:19
    • 1

      @lucjah Thanks! The 100th post was 'just' a comment to another post so this feels more like the 100th :)

      Valentino Urbano avatar Valentino Urbano | Mar 02, 2019 22:38:45
contact: email - twitter / Terms / Privacy