Upgrade to Pro — share decks privately, control downloads, hide ads and more …

DevOpsDays Cuba 2016: Ignite - Docs as Code

DevOpsDays Cuba 2016: Ignite - Docs as Code

Author: Genry Leyva González
Summary:
Forma simple de creación de documentación. Documentación como código. Entorno de integración y entrega continua para revisión, pruebas, mezcla. Uso de la misma infraestructura de desarrollo para la documentación. Generación automática de documentos en diferentes formatos. Entrega de documentación junto con el producto.

DevOpsDays Cuba

October 20, 2016
Tweet

More Decks by DevOpsDays Cuba

Other Decks in Technology

Transcript

  1. Genry Leyva González
    @genrylg
    www.linkedin.com/in/genrylg
    [email protected]
    Ops Team at

    View full-size slide

  2. DOCs as Code

    View full-size slide

  3. User’s Manual
    Install Manual
    README Administration Manual
    Contribution Guide
    API Specification

    View full-size slide

  4.  Poor Collaboration
     Lack of versioning
     Documentation at
    the end
     Different cadence
    between release
    and doc
     Developers not
    involved
     Difficult to obtain
    different file
    formats

    View full-size slide

  5. DOCs as Code
    2007 2008 2009 … 2014 2015 2016
    collaboration developers involved
    review & merge testing & publishing
    semantic versioning

    View full-size slide

  6. Next
    In
    Progress
    … UAT
    Pending
    for Doc
    Being
    Documented
    Doc
    Ready
    Staging
    feature
    feature
    feature
    feature
    feature feature
    feature
    feature feature
    feature
    feature
    feature feature
    Documentation Stages

    View full-size slide

  7. Next
    In
    Progress

    Dev
    Done
    Pending
    for Doc
    Being
    Documented
    Doc
    Ready
    Staging
    feature
    feature
    feature
    feature
    feature feature
    feature
    feature feature
    STEP 1
    STEP 2
    STEP 3
    STEP 4
    STEP 5
    feature
    feature
    feature feature
    Every feature is
    documented
    as part of a delivery
    process
    Definition of DONE

    View full-size slide

  8. Create feature
    branch for a
    new feature /
    user story Write new or
    edit existing
    documentation
    Create pull
    request
    Automatic
    Testing
    Review
    Merge to the
    develop branch
    Regenerate
    documentation
    files
    Merge
    Trigger of CI
    plan to publish
    CREATION
    PROCESS

    View full-size slide

  9. Branch by
    feature
    Git on
    Gitlab
    Continuous
    Integration

    View full-size slide

  10. Semantic Versioning

    View full-size slide

  11. lightweight markup
    language
    plain text
    formatting
    it can be
    converted to
    many formats

    View full-size slide

  12. PANDOC
    IN: more than 20
    OUT: more than 30
    CLI

    View full-size slide

  13. Doc
    Proyects
    in Gitlab

    View full-size slide

  14.  Simple way of writing
    documents
     Collaboration
     Writers have a similar
    workflow to developer

    View full-size slide

  15.  Based on developers' infrastructure
     Ops team as enablers
     Documentation delivered along with a product

    View full-size slide

  16. genrylg
    genrylg
    DOCs as Code

    View full-size slide