Skip to content

Latest commit

 

History

History
210 lines (168 loc) · 3.36 KB

what_is_documentation.adoc

File metadata and controls

210 lines (168 loc) · 3.36 KB
Raw

By the way…​

🧐

What is Documentation?

Sharing knowledge

When?

Knowledge needed for a long period of time?

→ Documented

Knowledge needed by a large number of people

→ Documented

Knowledge valuable or critical

→ Documented

Default

→ Don’t

Generic Knowledge

  • Programming languages

  • Developer tools

  • Software practices

    • DDD

    • patterns

    • CI

  • Mature sector of the business industries

    • Pricing in finance

    • Supply Chain Optimization in e-commerce

    • → Industry standard books

Good news everyone!

The Generic Knowledge is already documented in the industry literature.

→ Learn Generic Knowledge

→ Link to sources of Authority

  • Training

  • Conferences

  • Books

  • Blog posts

  • Standard Vocabulary

…​

Focus on specific knowledge

  • Not (yet) shared with other peers in the same industry.

  • More expensive to learn

  • That takes practice, making mistakes to earn

  • That Deserves more attention

  • Only you can take care about it

As a professional, you should know enough of the generic, industry standard knowledge, in order to be able to focus on growing the knowledge that’s specific to you particular ambitions.

Stable vs Unstable

Stable

  • Standards

  • Most of parts of common industry

Not Stable

  • Marketing

  • Company names

  • Dates

  • People

  • Design decisions

How to deal with Stable/Unstable?

Stable

Learn & refer to it

Unstable

Automate it as much as possible when it is useful

Internal vs External

Internal

  • Code

  • Tests

  • Manifests

  • Wiki as code

External

  • External Wiki

  • Ms Office documents

  • Project management tools

  • External: Ms Word, Wiki, Jira…​

    • Advantages can be convenient for the audience and for the writers

    • Inconvenient: hard or impossible to make it up to date

  • Internal

    • In Situ

    • Machine-Readable

Problems with Internal Knowledge

  • Not accessible

  • To many (noise)

  • Scattered everywhere

  • Implicit (e.g. design pattern visible only if we know it exists)

  • Unrecoverable (lost)

  • Unwritten

Augment it, make it accessible for it’s audience.

  • Not accessible…​ (e.G to non technical people)

  • To many (noise) only a few lines may be relevant for a question

  • Scattered everywhere

  • Implicit (e.g. design pattern visible only if we know it exists)

  • Unrecoverable (lost) (people left)

  • Unwritten: in someone’s brain and only the consequences are in the system…​

Stable • Evergreen document

Useful content for a long period of time

  • Short with not much details

  • High Level focus

  • Goals and intention (not implementaion details)

  • More business oriented that technical

Here traditional documentation is OK 👍

  • Evergreen : Ce qui est stable = ce qui est toujours vrai