Cutter gen culture_doc


Published on

Generating a Culture of Doc, or Bribes that Work, getting engineers to do the write thing.

Published in: Technology, Business
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Name is Leah Cutter
    I work for We do customer relationship management software.
    We're a cloud company.
    My title is KMS.
    I live in Seattle. Salesforce HQ is in San Francisco. I am a remote employee, and telecommute.
    I have degrees in English Lit and Comp Sci
    I also write fiction, have several published novels and short stories
  • I saw some of you scratching your heads at my title.
    What do I actually do?
    Short answer is technical writer
    Long answer:
    Provide framework for engineer generated content
    Work as internal consultant for all of R&D as well as TechOps for specs, sites, and wikis
    Give lots of presentations, brown bags, and hold knowledge sharing events
    As well as determine strategy for internal doc content management, such as file name standards, content location standards, etc.
  • I promise this is the only slide with this much text — read it while you can
    Notice there’s no customer facing content that I’m responsible for. It’s 100% internal.
  • Engineers don’t use the product they create. Customer facing doc doesn’t affect their day-to-day work life. They don't use the product or the documentation like your customers.
    Usually, the engineers who care about doc are the ones who have to answer customer calls.
    One of the key ways to get engineers to care about doc is to introduce them to doc that they do care about, that documents things that they do use every day.
  • So your first step is to find internal tools that engineers use all the time.
    Then, don’t just write that doc. Either make your engineers write it, or collaborate with them on it.
    I know that was a big bomb. I can hear the screams from here.
    Engineers write doc?
  • We all have horror stories about the inadequate doc an engineer handed you
    Which is why you have to help them.
    However, not all engineers just produce crayon drawings.
    Sometimes they can be quite eloquent.
    Why else should engineers generate internal content?
  • SFDC hires tech writers in a strict ratio to developers. I don't remember what the ratio is. It's a good start at making sure writers aren't completely overwhelmed.
    However, even at a company that values documentation like SFDC, there’s always too much work and not enough writers.
    Plus, companies are always looking for how to do more with less, and doc is frequently what gets cut first
  • Another reason why engineers should generate content about internal processes — it’s all in their heads
    Suppose that you have one engineer, let's call him Bob. Bob is the only one who really understands your build process, how you generate the application from all the code your devs are working on.
    Then Bob leaves. No one can get the build to run. Now, you’ve wasted three weeks of 30 engineer’s time.
    This goes directly to R&D productivity. Note that I'll be mentioning that a lot.
  • At SFDC, not great, but okay about writing stuff down
    However, were no standards about what lived where. 6 different places for a tech spec to live.
    Good luck to the new hire, new manager, new doc writer. Or even another team that needed to collaborate.
    They have to go ask people, which means more meetings, less time to actually work, and cuts into R&D productivity (You be noticing a theme here…How documenting internal processes will actually save your company money)
  • I know I haven't convinced all of you of the importance of internal doc. So let me give you an additional argument that you may be able to take back to your management.
    Traditionally, tech writers wrote doc for people who installed or administered the software. In a cloud company, one of the customers is now TechOps, an internal team.
    In addition, if you're hosting government data, welcome to the world of internal process audits, conducted by lawyers who will want to see all of your internal process documentation.
    Devs no longer write code for off-the-shelf servers in known configurations. In the cloud, configuration is custom and proprietary. And the performance of your software may well depend on how well that proprietary design is documented.
    This means that documenting internal processes just went from nice-to-have to vitally important.
  • To address these issues, like R&D productivity, onboarding, process audits, and other things, SFDC created the internal documentation team.
  • I have my current position due to a grass-roots effort. The engineers were so concerned because they were wasting so much time explaining things over and over again. They knew with just a little help, they could be much more productive.
    I wrote the job description for it. I'm kind of living the dream. I know not all of you are. I stand here as an example of what's possible.
    The team had only been around for about a year, but already, writers focused on external customer doc are seeing the difference in their teams. Our internal team is changing the entire culture of R&D. It's obvious in big as well as small ways.
    So how do you get engineers to do the write thing, and start writing internal doc? Or collaborating with you to write this type of doc? What sort of techniques work to begin this transformation? What can you do, next week when you get back to your company, that will help start this change?
    (See the subtitle of the talk--bribes that work.)
  • The first thing is to find like-mined people.
    At Salesforce, we have a tool called Chatter. It's like Facebook for the enterprise. It allow people to form groups and follow things. For more information about Chatter, I hope you saw Sabine's excellent presentation on social enterprise networks. Look up her slides.
    Because of Chatter, the group was able to self-organize.
    For you and your company, get creative: Have a brown bag. Maybe a Cheese & Whine session. Generate a mailing list. Create a forum. Hold an after work happy hour (BYOB)
    You can present this to your management as a stretch goal, or one you'll allocate x% of time to, then present the results as a brownbag, or even an executive presentation. Measuring the ROI is difficult, but it’s possible, particularly if engineers are answering a lot of internal process questions that suddenly go away.
  • The second thing – Don’t go it alone!
    Take the big problem, break it into pieces and parcel it out.
    All good tech writers are actually project managers.
    At Salesforce, we work in an Agile organization, which means small teams that are able to self-organize. One of the things that's worked for us are virtual scrum teams for the work. Everyone gets assignments, the work is officially tracked, you meet regularly to report on your progress or any blockers.
    Or maybe you form a monthly brown bag where you all bring your laptops into a room and work together on a specific area that needs further doc.
  • About one third are eager — filled with self-enlightened altruism. They know that spending a few hours documenting something will save them hours and days later down the line.
    About one third are willing to help, though not necessarily eager. These tend to be the less experienced engineers. They need templates, clear guidelines on what to do.
    And about one third are the curmudgeons. They always need to be the smartest person in the room. Flattery usually works with them—acknowledging they are that smart, and that they need to help the rest of us.
    So what ways have we been able to successfully get engineers to either create documentation, or share knowledge?
  • As a documentation team, we hold office hours. Any engineering team can contact us for a consultation about their internal communications, such as their team site, or maybe they have a large new tool that everyone will be using internally and they need some help figuring out the message. Or perhaps they already have a large amount of documentation that they need help organizing.
    We've also been able to demo new tools for teams to use instead of the old ones, like using a knowledge base.
    We teach people to fish during office hours, instead of giving them fish. The ROI on office hours is off the charts. If you come to Lavacon next year, we'll hopefully have a talk that shows all the ROI statistics (it's still being developed.)
  • Choose a SPECIFIC TIME.
    Salesforce has three releases a year, so we hold this event one week after release freeze, which is generally a quieter time for engineers.
    —Chatter team page, team site, list of other projects, like README files, specific packages in code base that need comments
    —You don’t have to generate the list of other projects, get engineers to do that ahead of time
    And again, you could propose this as a stretch goal to your management, to show leadership in your career.
    I do a 'drip' campaign ahead of time, weekly email announcements that are clever and based around the theme.
    Afterward, socialize all projects, recognize every engineer. Also, hold a retrospective to record what went well, what didn’t go well, what to do better the next time. Then present the results to your management.
    Our doc hack days have resulted in some truly spectacular results, like a tool that automatically generates dependency diagrams from the code, a glossary that's integrated with the IDE engineers use (Eclipse) and others.
    They’ve become so popular that teams are now holding their own documentation hack days.
  • In addition to just getting more processes documented, we also just want to increase communication across all of R&D and TechOps.
    So once a release, in addition to the doc hack days, we have the STARS event: Salesforce Technical Architecture and Review Sessions.
    This is just another way of getting information out of the heads of engineers and spread across the organization.
    STARS is an all afternoon event, with several parts. Always organized around a specific theme. Past themes have included "back to basics" which was how to build out our data centers, productivity, and security.
    The first is the Chief Technology Officers fireside chat – moderated talk, and yes, we play a burning yule log behind them.
    The second part is a panel of cross-team experts all involved in the theme. We try to get a very wide diverse team, such as release engineering, techops, doc, locationation, marketing, engineering, etc.
    The third part is a series of Lightning talks – 15 minutes of PRACTICAL tips about a topic.
    A quote from one of the engineers:
    What a well organized and incredibly informative event! Thank you! Comparing lightning talks to stagnant documentation, this is so much more effective. We can hope to improve on our docs, but when looking at the time put in and the benefit taken out, this must be the most efficient knowledge dissipation mechanism.
  • This isn't a one-way street, you know. You have knowledge as a writer that engineers need. I've given a bunch of well-attended presentations, such as
    Writing tips for Engineers
    Best Practices for Tech Specs
    The Google and You
    What Technical Writers Do
    Preventing Doc Rot
  • Need to know what the code is supposed to do, not just what it does.
  • Feel free to use these slides in your own presentations to your content experts
  • Cutter gen culture_doc

    1. 1. Generating a Culture of Doc (subtitled: bribes that work) Leah Cutter @LavaCon @SalesforceDocs
    2. 2. Who am I? • Leah Cutter, Knowledge Management Specialist, • Technical writer since 1985 @LavaCon @SalesforceDocs
    3. 3. KMS – huh? @LavaCon @SalesforceDocs
    4. 4. Engineer generated content includes: • Internal processes, such as generating code comments, coding standards, build procedures, etc. • Bill of Materials • README files • Knowledge base articles • Specs • Team sites • Team wikis • Email announcements • Architecture diagrams • Internal white papers • Internal newsletters or blogs @LavaCon @SalesforceDocs
    5. 5. Internal doc? But I have a hard enough time getting engineers to care about customer facing doc! @LavaCon @SalesforceDocs
    6. 6. Culture of Doc Engineer generated content for the win! @LavaCon @SalesforceDocs
    7. 7. Why should THEY write any doc? Some writers believe this is all an engineer can do @LavaCon @SalesforceDocs
    8. 8. Writers are outnumbered Ratio of writers to engineers: @LavaCon @SalesforceDocs
    9. 9. Where knowledge exists In the heads of engineers @LavaCon @SalesforceDocs
    10. 10. Where knowledge lives when it isn’t in someone’s head In too many places, no federated search, and no best practices for creating new content @LavaCon @SalesforceDocs
    11. 11. Really? Internal doc? @LavaCon @SalesforceDocs
    12. 12. Internal documentation to the rescue! SHAZAM!! @LavaCon @SalesforceDocs
    13. 13. Mighty internal writer warriors • • • • Internal architecture Internal processes, like building out servers and data centers Architecture white papers Internal knowledge sharing (that’s me!) @LavaCon @SalesforceDocs
    14. 14. But wait! • My company will never create an internal team, doesn’t prioritize doc, never have the headcount, never, never, never • See: Not made of gold @LavaCon @SalesforceDocs
    15. 15. Harness the power of internal champions • Find the people who are like minded – Nurture them – Give them a forum @LavaCon @SalesforceDocs
    16. 16. Don’t go it alone! • Your engineers know where the problems are • They may even have some ideas how to fix it • You need to provide organization and project management skills @LavaCon @SalesforceDocs
    17. 17. Breakdown of engineers My experience so far @LavaCon @SalesforceDocs
    18. 18. Office Hours @LavaCon @SalesforceDocs
    19. 19. Internal Documentation Hack Days @LavaCon @SalesforceDocs
    20. 20. Internal architecture review STARS Event (Salesforce Technical Architecture Review Session) @LavaCon @SalesforceDocs
    21. 21. Share the knowledge you have as a writer • Brownbags • Training @LavaCon @SalesforceDocs
    22. 22. Some text > no text @LavaCon @SalesforceDocs
    23. 23. But good code documents itself! • Bull • Only tells what it does, not intent – Tell me WHAT this thing is – HOW to use it – WHO to contact @LavaCon @SalesforceDocs
    24. 24. Let’s talk about the future @LavaCon @SalesforceDocs
    25. 25. This is your mind right after you've written some code Orderly, serene, and able to levitate stuff. @LavaCon @SalesforceDocs
    26. 26. This is your mind, six months later Good luck! @LavaCon @SalesforceDocs
    27. 27. And this is what it looks like to someone new, 2 years later If you’re lucky... @LavaCon @SalesforceDocs
    28. 28. Q&A @LavaCon @SalesforceDocs
    29. 29. Work Contact info: Twitter: @salesforcedocs Personal Contact info: @LavaCon @SalesforceDocs
    30. 30. Work Contact info: Twitter: @salesforcedocs Personal Contact info: @LavaCon @SalesforceDocs