XioNoX

Ingé. réseaux, voyageur, etc.

[Roman Dodin @ntdvps]

Being on "the other side" of the pipeline for the past couple of years, I started to understand better why good docs are so hard to cook. 😟

Probably the most widespread concern expressed in the linked thread is docs being login/pay-walled. There is not much I can say about this particular problem, only that it is usually out of Product Management's control. Typically a remnant of the past where C-level folks think we are still living in the sweet 90s, and gated access to docs protects intellectual property. Even typing this out brings me pain.

The quality of documentation, though, is something that product management (typically) has direct control over. But then why do we see stale docs, broken links, incompleteness, and lack of crucial examples?

Like it or not, what I experienced firsthand being a PM is that most of these problems are the byproduct of not having enough time allocated in the release cycle to PMs to prepare product descriptions, which are then taken by the Tech Writers team to write the actual docs.

In a nutshell, the workflow is
0. A new release cycle kicks in. For some vendors, it is quarterly, bi-yearly, etc.
Product Managers start to work on the assigned features slotted for this release.

1. Product managers lock up with engineering and work on a feature. For engineering to start working on a feature, they need to have a "product requirements" drafted by a Product Manager (PM).
These requirements describe how the feature should behave on a particular set of platforms, including scaling, limitations, API/Schemas, etc.

2. Once requirements are drafted, engineering can take this on and work on the code, including the Test team to validate it.

3. These requirements are the primary input for the Tech Writers team to write the actual docs.

4. Tech Writers do their best to digest the highly technical requirements document to write "proper" external-facing documentation. And here is where it gets tricky.
Teach Writes usually cover A LOT of product topics, kind of jacks of all trades, so they don't have as in-depth knowledge of the features when they start processing the requirements.
The better the job the PM does, the better the docs.
If PM's requirements are clear and structured and have examples, Tech Writers will have a much better time figuring it all out and producing a nice doc entry.
When tech writers draft the docs, they pass the ball to PMs for them to review and correct it.

5. And here we are at the very crucial step. For PMs, a feature documentation review is the last task before cutting the release date. This is where the pressure builds up, and presumably, a lot of handwaving happens.
"Ugh, I don't have time to review these docs, let's ship it as it is," is something that potentially leads to those documentation gaps.

Is there a way out of this vicious cycle? Someone mentioned "let network engineers write the docs". That's a noble idea, but then someone needs to suddenly find and hire tech writers with solid networking skills and pay them adequately.

But, hey, everyone is trying to make their docs as good as possible, it is just not as easy as it sounds 😇

And then some engineers teams do take the bottom-up approach and start the "tech magazine" where they explain the product features in a more consistent, blogger-y way.
Like we do at https://t.co/gxtWVRjr2L or Cisco does with @xrdocs or Juniper with their tech blog.
But this is not to be mixed with the product documentation, it is +- a blog.

[Caisses de grève (Gauche Gaza / Antifasciste) @caissesdegreve]

"Homelander"

[Marcel @realmarcel1]

Le Conseil Constitutionnel est retranché derrière des centaines de casques et de boucliers.
A qui tu vas faire croire que la France de Macron est une démocratie ?
🎥@LibreQg
#greve13avril #manif13avril

[Claire Nouvian @ClaireNouvian]

🚨 Je relaie rarement les interventions d’élus, mais cette interpellation du sénateur @JacquesFernique est tout simplement EXTRAORDINAIRE.

En moins de 2min, il fait voler en éclat les mensonges et le cynisme anti-ecologique d’ @HerveBerville .

Ecoutez, partagez.

[Claire Nouvian @ClaireNouvian]

🚨C’est GRAVISSIME: en pleine nuit, les bureaux de l’office français de la biodiversité ont été incendiés à Brest. Dans un contexte de colère des pêcheurs, la situation est devenue explosive.

Voici les raisons du chaos
(SPOILER: la responsabilité d’ @HerveBerville est énorme)

[TracketPacer @TracketPacer]

hey so did y’all know about the oral part of the CCNA exam?

[actif-trafiC @ActifTrafic]

Ca me paraît être un bon deal.

#étalementurbain

[Antoine Phileas @PhileasGatsby]

@VaugirardG @solcy_conseil @isaduvelo @njeannete @FlorianSitbon @JRippert @mairie15 @AnthonySamama @PeS_15e C'est trivial pourtant, c'est pas bien compliqué 🤷

[Pingex (Raphaël) @PingexWasTaken]

Free qui débarque enfin sur FranceIX ? 🤨

[Free 1337 @Free_1337]

Un acte de vandalisme a été constaté sur le pylône haubané de la commune de Changé (53) au nord de Laval. Notre réseau mobile risque de subir quelques perturbations dans la région pour un temps indéterminé. Les services d'urgences ont été informés et une enquête est prévue.

[Free 1337 @Free_1337]

1/2 Un acte de vandalisme sur notre infrastructure fibre entraine depuis cette nuit de fortes perturbations de service (dégradation de service et de bande passante fixe/mobile) sur la région de Marseille.
Nos équipes sont mobilisées depuis 3h du matin.

[Common Fate @CommonFateTech]

hope this helps 👍

[Forrest Brazeal @forrestbrazeal]

new little song:

"The Re-Org Rag (I'm My Own VP)"

[Tim Urban @waitbutwhy]

Hidreley Diao uses AI to capture what historical figures would look like if they were modern people.

George Washington:

[Jeremy Stretch @jstretch85]

Virtual chassis be like

[Florian Lainez @overflorian]

Et soudain, perdu en plein milieu de la Biélorussie https://t.co/inuwpFr26L #LesPépitesOpenStreetMap

[Florian Lainez @overflorian]

Avant, je ne savais pas comment fonctionnait le GPS, mais ça c'était avant https://t.co/I5AVxcEHyc bonne trouvaille de @XioNoXfr

[Le Gorafi @le_gorafi]

Oh et puis merde, vous l'avez cherché, démerdez-vous sans nous.

[wac @_wac]

I guess I now know why an offshore law firm was offering me ever increasing amounts of money for https://t.co/5HMmqq9zU6 over the past few months. Sorry Zuck, it still belongs to my dog.