# Dev Spaces 3.0 ## Crafting the docs for a major release <!-- Put the link to this slide here so people can follow --> slide: https://hackmd.io/@ffloreth/dev-spaces-3-0-docs#/ --- ## Highlights :high_brightness: * :green_book: One guide per persona * :recycle: Content cleanup * :new: Focus on customer stories * :handshake: Writer pairing with engineer * :classical_building: Business as usual * :sunrise_over_mountains: Upstream first * :honeybee: Open Source --- ## A major release ## :new: * :books: Content * :derelict_house_building: Stale * :building_construction: New * :printer: Processes and delivery * :robot_face: Breaking changes opportunity * :repeat: Handle transition --- ## One guide per persona ## :green_book: * :bearded_person: Administrator :blue_book: Administration guide * :blond-haired-woman: User :green_book: User guide ---- ### Previously ### :books: * :bearded_person: :books: Administration guide Installation guide * :mag: Searchability * :link: Cross guide links validation * :blond-haired-woman: :green_book: End-user guide * :construction: Style ---- ### Moving content ### :mountain: * :mag: Identify * :tractor: Move * :fast_forward: Redirect --- ## Content cleanup ## :recycle: * :recycle: Obsolete content removed * :tractor: Remaining content adapted ---- ### Outdated content ### :cold_sweat: * :derelict_house_building: :building_construction: New workspace engine * :derelict_house_building: :building_construction: Unique operator-based installation * :derelict_house_building: Most configurations obsolete * :derelict_house_building: :building_construction: Remaining procedures changed ---- ### Our options ### :world_map: * :recycle: Recycle * :droplet: Start fresh ---- ### Start fresh? ### :droplet: * :mag: Identify * :tractor: Copy * :pencil: Adapt ---- ### Start fresh fail ### :broken_heart: * :construction: Stalled * :helmet_with_white_cross: Change for :recycle: strategy ---- ### Recycle ### :recycle: * :mag: Identify * :recycle: Remove * :fast_forward: Redirect ---- ### Adapt ### :revolving_hearts: * :mag: Identify * :handshake: Assign 1 engineer 1 writer * :pencil: Adapt --- ## Stories ## :new: * Emphasis on user stories for new content * Answer to customer questions --- ## Writer pairing with engineer ## :handshake: * :sunrise_over_mountains: Clarity * :peace_symbol: Collaboration * :speedboat: Velocity ---- ### Blog posts? ### :busts_in_silhouette: * :bearded_person: Engineeer: write blog post * :blond-haired-woman: Writer: simple language review * :blond-haired-woman: Writer: write doc inspired by blog post * :bearded_person: Engineer: test procedures ---- ### Blog posts fail ### :broken_heart: * :calendar: Engineers missing the schedule * :books: Duplicate work for writers * :loop: Poor collaboration * :hourglass: Frictions and delays --- ## Business as usual ## :classical_building: * Modularity * Consistency * Minimalism * Style guide ---- ### Modularity ### :house_buildings: * Continuous modularization effort * Use the `:_content-type:` attribute * Antora `pages` with content ---- ### Project consistency ### :house_buildings: * Prerequisites * Additional resources * Attributes * Che docs style shared with blog https://github.com/eclipse-che/che-docs-vale-style ---- ### Consistency with OpenShift docs ### :house_buildings: * Link names * Listing tools in prerequisites ---- ### Minimalism ### :building_construction: * Point to external docs rather than copying * Shorter pages * Document only CLI flows for configuration ---- ### Style guide ### :microscope: * Red Hat style https://redhat-documentation.github.io/vale-at-red-hat/ * Write and test rules * Documentation for users and contributors * Automation --- ## Upstream first ## :sunrise_over_mountains: * :printer: New publication process * :robot_face: More validation automation * :canoe: Downstreaming refactoring ---- ### Publication ### :printer: * :unlock: Decouple content and publication logic * :unlock: Simplify publication chain * :books: Multiple versions published ---- ### Validation ### :robot_face: * :new: Antora to plain AsciiDoc * :new: Unused pages, modules, images * :new: Links required by dashboard ---- ### Downstreaming ### :canoe: * Entire refactoring * Simpler * More readable output --- ## Open Source ## :woman-playing-water-polo: * :open_book: Red Hat style guide * :open_book: Antora guidelines * :open_book: Educational scripts ---- ### Vale at Red Hat ### :robot_face: * :open_book: Documentation for users and contributors * :robot_face: Write and test rules * :robot_face: Automation: test rules, build docs, triage * :speaking_head_in_silhouette: Give directions to the project * https://redhat-documentation.github.io/vale-at-red-hat/ ---- ### Antora guidelines ### :open_book: * :open_book: Generic guidelines inspired from che-docs implementation * :robot_face: Automation: build an validate the docs, template repository * :open_book: https://antora-for-modular-docs.github.io ---- ### Educational scripts ### :open_book: * Long parameters * Comprehensive comments * Clarity rather than compacity --- ## Wrap up ## :sandwich: * :green_book: One guide per persona * :recycle: Content cleanup * :new: Focus on customer stories * :handshake: Writer pairing with engineer * :classical_building: Business as usual * :sunrise_over_mountains: Upstream first * :honeybee: Open Source --- ## Thank you! ## :sunrise_over_mountains: