How to enforce discipline of writing (better, more extensive) Documentation?

Microsoft UMbR31
Jun 21, 2018 13 Comments

Need some advice, small startup, not Microsoft.

How do I get engineering teams to write better public facing documentation? (For example, provide more examples, screenshots, alternatives, links to other relevant pages, updating when new APIs etc). Do you guys hire a part time documentation person, assign x% sprint time to this? Have you seen something has worked in a small company of under 300 devs?

comments

Want to comment? LOG IN or SIGN UP
TOP 13 Comments
  • Amazon ymdO38
    Convince them that it is not a wasted effort on their part. Most documents are never read or used after they are written. They usually drift from reality once written. We hate waste. We hate busywork. Make it worth our while.
    Jun 21, 2018 4
    • Microsoft UMbR31
      OP
      How do I do this? Is it a speech? Is it a gift card? What will convince?
      Jun 21, 2018
    • Amazon ymdO38
      When was the last time that documentation was actually used?
      Jun 21, 2018
    • Amazon ymdO38
      And please review before giving out incentives: http://dilbert.com/strip/1995-11-13
      Jun 21, 2018
    • Amazon ymdO38
      That said, reducing the number of time that the same questions were asked was valuable to me and encouraged me to write more documentation. Prace and quiet had value to me.
      Jun 21, 2018
  • Autodesk omni
    We do an entire sprint of just that when need to. Working pretty well
    Jun 21, 2018 2
    • Microsoft UMbR31
      OP
      Thanks, definitely one of top options in my mind.
      Jun 21, 2018
    • Square / Eng nom🍔
      Even just a "doc day" which is focused on docs could be effective. Add special catered lunch and some form of success measure for extra motivation.
      Jun 21, 2018
  • Google / Eng Fakir
    Add it to “Definition of Done”
    Jun 21, 2018 0
  • Microsoft dVGc27
    Instrument page views, maybe even time spent per page. Then link this to a dashboard to encourage engineers. ?
    Jun 21, 2018 0
  • Square / Eng nom🍔
    Assuming the team is generally motivated and high performing, you're probably not giving them enough context about what "good documentation" means. It generally takes years to understand what good coding is, why would expect them to automatically know what good documentation is and how to do it well?
    Jun 21, 2018 1
    • Microsoft UMbR31
      OP
      That's true. Created a few benchmark 'great documentation's for some of the APIs but getting them to adopt is hard.
      Jun 21, 2018
  • Google / Eng
    NoFizzBuzz

    Google Eng

    PRE
    Apple
    NoFizzBuzzmore
    Tie it to perf.
    Jun 21, 2018 0