#Dev docs preview

1 messages · Page 1 of 1 (latest)

clear ferry
#

Please comment and discuss here

#

@narrow pilot @slim reef @cobalt haven @grim wharf @languid jewel @cursive shale

#

(trying not to ping people who are sleeping)

languid jewel
#

My work VPN blocks that site. I will have a look from my personal PC and provide feedback tonight

slim reef
#

Copied from another thread…

I think the common docs can show the essential stuff that's common in every SDK, and do it by example. In other words, I see them as having different purposes.

Mostly, a user would just follow the common docs normally and only in the end continue on the more "advanced" language docs, which can be written in a different "tone", more to be used as reference and go into some details that allow a more in-depth understanding of how it works in the user's chosen language.

TL;DR:

  • Common docs (practical)
    • tutorial (learning oriented) or how-to guides (problem-oriented)
    • show by example (copy+paste)
    • most common use cases that work across SDKs
    • short explanations
  • Language docs (theoretical)
    • conceptual guides (understanding oriented) or reference guides (information oriented)
    • specific to SDK implementation details or DX
cursive shale
#

My preference is option A, since it makes clear that there's a common underlying pattern/platform and lets you see the language examples side-by-side. Agree with what Helder said overall

clear ferry
#

My preference is to start with option B, then gradually aim towards option A over time.

I think if we start directly with a fully centralized model, we will make wrong assumptions, and we will be stuck having to retrofit everything into an overly rigid model from the start.

I think it's more realistic to start with standalone SDK-specific dev guides, deal with the duplication behind the scenes, and over time, build the confidence to make it more centralized later.

#

I think if we start with option A in practice, readers will have to jump back and forth between the common and SDK-specific sections.

  • "Here is a simple example of concept Foo in all languages" (reader selects Python).
  • Python comment says "note that async is optional, sync mode is supported too, see <link to a page in SDK dev guide>
  • Reader is now in SDK dev guide. Reads out-of-context information about sync vs async.
  • Reader navigates back to common guide to keep going
cobalt haven
#

Depending on the mood I'm in, I generally read documentation about new tech (ie. new to me) in two ways:

  • Read all the basic concepts before going hands on
  • Do the hello world example in 1 minute, otherwise it's too complicated

I kinda think both paths should be available in a documentation these days.

Another thing that often frustrates me when reading documentation is having to navigate between different sections for seemingly connected parts. The Temporal docs come into mind: they also have language specific documentation and I'm often lost between those pages and the "common" concept pages. Having to remember which information is where is annoying. (Which makes me lean towards option B)

#

I found this documentation "framework" recently: https://diataxis.fr/ It might be interesting for you.

Diátaxis

The Diátaxis framework solves a problem of quality in technical documentation, describing an information architecture that makes it easier to create, maintain and use.

languid jewel
#

I looked at the preview before reading any of the comments here and I personally couldn't figure out a preference after skimming it. For me either doc works they both have pros and cons. If I had to pick, I think I would go with option B. Mainly because if I'm a Go developer, I wouldn't necessarily care about the other languages. I would directly jump into "Developing with Go" and follow the guide. Jumping between "Module basics" and Go sections may feel tedious.

Tldr: Option B