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

Workflow for documentation in Open Source projects

Ronny Trommer
February 15, 2016

Workflow for documentation in Open Source projects

Talk given at Chemnitzer Linux-Tage 2015.

Ronny Trommer

February 15, 2016
Tweet

More Decks by Ronny Trommer

Other Decks in Technology

Transcript

  1. Motivation started as OpenNMS user Experienced the lack of docs

    Found friends wrote a book 2nd Edition another year?
  2. Why? Empower people to use your software in the most

    efficient and right way. http://goo.gl/7M4YeZ
  3. Outdated It’s just wrong Explain stuff you already know Does

    not exist Informiert den Techniker! Problems with docs?
  4. • Integration in development • Define a workflow for contribution

    • Allow tracking of documentation issues • Integrate in review process • Add docs to your acceptance criteria • Iteration, Iteration, Iteration Treat docs as you treat source code
  5. + +

  6. http://xkcd.com/1285 Review for docs • What is written in monospace

    • When use italic • When use bold • Table formatting —> easier to read • JIRA links and JIRA number Formal
  7. http://xkcd.com/1285 Review for docs • Native speaker, language, grammar •

    Complete • Useful • Iteration on Pull Request Content
  8. • What is really version control relevant • fast vs.

    slow changing • Strong related to OpenNMS version • Slice by target group - User vs. Developer • Search for patterns and components Divide and Conquer
  9. Dashboard Dashlet 1 … Dashlet n Monitors for service tests

    Monitor 1 … Monitor n Data collection Collector 1 … Collector n
  10. OS independent Graph UML + PNG Free of charge …

    even commercial redistribution and use in automation
  11. Credits: ! Neo4j for AsciiDoc format conventions Spring for pointing

    us to AsciiDoc AsciiDoctor for building the cool tool chain Friends and community members for discussions