Skip to content

Latest commit

 

History

History
218 lines (196 loc) · 12 KB

README.md

File metadata and controls

218 lines (196 loc) · 12 KB
Raw

#Write the Docs A conference on writing documentation. These notes are notes, not a stenographic record. They're also not spell checked.

##Monday

###Flow: A Permaculture Approach to Documentation Homer Christensen

  • Applying Permaculture idea(l) to docs:
    • Observe, Design, Evolve
  • Project Planning: Patterns * When planning projects, you’re using what you’ve got to reach your goals. * If living systems have natural proclivities, what are the proclivities of your group? * This is a restatement of a basic leadership idea: know your people, know your strengths and weaknesses
  • Design
    • Zones are ‘areas of access’ in permaculture.

###Communities are Awesome - Ali Spivak

  • MDN, the mozilla developer network, is an OS wiki; relies upon the community
  • MDN is trying to doc everything that matters to developers. This is difficult since the web is big. (This means that MDN is big, too.)
  • Leveraging the power of the community lets MDN document as much as it does. There's paid staff and there's community.
  • Benefit of community is that it gives you a wide range of experience, opinions, backgrounds. This lets you know what matters to users (and users in different contexts).
  • Important to see users as peers; they're not your minions. (Great word, Ali.)
    • Users are 'partners on a journey'.
    • You don't offload crappy work on them, you don't tell them what to do.
  • Provide opportunity.
    • If you say 'Hey, X needs some documentation', people are likely to take you up on it.
  • Intrinsic (internal) motivation is important
    • Users will help because they want to, because they feel pleasure from doing so.
    • People like contributing their expertise to a large audience of peers.
      • e.g. Burning Man
  • Three Elements of Motivation:
    1. Autonomy
    2. Mastery
    3. Purpose
    • Check out the book Drive for more about motivation.
  • The importance of values
    • Values (clearly stated) give communities something around which to coalesce.
    • Clearly these need to be organically developed.
    • If your company adheres to and exemplifies these values, this makes it part of the community, not some asshole in a suit treating the community members like unpaid idiot minions.
  • Collaboration helps you to avoid making wrong decisions.
    • If users don't want to do it, maybe it isn't the right thing to do.
  • There isn't necessarily one best way to build a community.
    • What are you passionate about? How can you share that passion with others?
    • What opportunities can you provide to the community?
    • How can you create community?
    • How can you bring more people in?
    • What opportunities can the community bring to you?

###The New Sheriff in Town: Bringing Documentation Out of Chaos - Heidi Waterhouse

  • Believe in your own expertise and authority. Then, get to writing.
  • Set Up Shop:
    1. Make a seating chart Make a seating chart of who is who in the office.
      • Names, specialties
    2. Map existing documentation e.g. marketing whitepapers, wikis, etc.
      • Make sure you have access
      • Be willing to dig.
      • You need to see everything in the compay except salaries.
    3. Get to know the neighborhood (competitors and users)
      • Read competitiors' docs.
      • (users?)
  • Draw Fast
    • No time for frills
      • just start writing
    • Deliver fast and often
    • Emergencies first, precisions second
      • formatting, readability, localization comes second to putting out fires.
  • Save the townspeople
    • Address biggest pain point
    • Provide structure to ask q and get feedback
      • Bugtrackers
      • Declare docs equivalent to code. Needs to be pushed with code.
      • Track doc bugs with code bugs.
        • Provides accountability.
  • Check for scorpions (these are situations, not people)
    • Hoarded documentation Is there a bunch of unreadable docs out there?
      • DO people feel some sort of propriatary interest that is keeping them from sharing their docss?
    • Stuff from the last sherrif
      • Did previous writers leave behind a bunch of junk that needs to be taken care of?
    • Bring in the vigilantes
      • Are people writing docs and not thinking of themselves are part of the doc team?
  • Build infrastructure
    • After you put out the fires, make sure you've got structure to keep things going.
    • Go to meetings. Make sure that docs are part of the agenda.
    • Plat your documents - Plating is designating spaces for certain use.
      • Can customers use the product?
      • Can installers configure it?
      • Can advanced users customize it? (e.g. apis)
      • Can users fix things when they go wrong?
      • You'll need a reference guide for when things get too big to remember off the top of your head.
        • Or for when you get bitten by a rattlesnake/go on vacation and aren't around to give all the answers.
  • Sheriff or Texas Ranger?
    • Do you want to shoot the bandits and leave? Then you're a Texas Ranger
    • Do you want to live in the town and be part of the community? Then you're a sherriff.

###Ignorance Is Strength: Writing Documentation By Learning As You Go - Amalia Hawkins

  • People who are have innate understanding of materials often aren't the ones who are the best at explaining it.
  • How do you learn an existing codebase? Read the code, look @ user-facing documentation, ask sr engineers questions.
    • Reading code is good (tells you how & what), but not why? (e.g. What was the developer's intention in writing the code the way it is written?)
  • Internal documentation helps a company to avoid growing pain, scaling both horizontally and vertically.
    • If you've got (good) technical docs, it's easier for new engineers to hit the ground running.
  • Lessons:
    • Write Anything
      • Once something exists, it can be massaged into something good.
      • That cliche about not letting perfection being the enemy of existing.
    • Find your allies
      • Don't believe that you're confused because you're stupid/a n00b/whatever else that's negative.
      • If you're confused, others probably are, too.
    • Spread out the work content, format, critique
      • When you teach, you learn.

###Did It In Minutes: The Art of Documenting Meeting Notes Mo Nishiyama

  • Hey, meeting minutes are important. Someone should be keeping them.
  • During meetings, sketchnotes are fun but not always productive.
  • Meeting notes shouldn't just barf back what was said. (regurgitation -> curation)
  • So how should you keep meeting notes?
    • Understand your audience Who isn't there?
      • Who will need to read these notes?
      • Why will they read them?
    • Shared Need
      • What will people get the most from?
        • eg Avoid chronology. Frontload the important stuff.
    • Write the Facts
      • Meeting minutes should include what's important. You're not a courtroom stenographer; you can summarize.
    • Engage your subject matter experts
      • Before publication, ask experts questions about your minutes. That'll help you to clarify, qualify, classify.
    • Make your action items clear
    • Use collaborative tools
      • Makes it easy to fix mistakes, typos, &c
    • Use templates to save time
    • Always tell: Who, Where, What
    • Easter Eggs
      • Adding in fun stuff will make people read your notes.
  • Exceptions:
    • If your organization loves chronology, keep it.
    • If you are a courtroom stenographer, record everything.
    • If your org has a style guide, stick to it (until you can change it).

###Hacking the English Language - Nina Vyedin

Or, what we can steal from programmers

  • Documentation can be helped by giving writers a default framework in which to write/work.
  • Have templates for oft-written stuff: blog posts, references
  • Make sure you know what question a doc is trying to answer.
  • make a spec for your doc and make sure everyone involved knows the specs.
    • what are the questions you're answering?
    • who is the audience?
    • what is the current state of documentation?
      • new content, existing content (including 3rd party docs)
    • what's the work plan?
      • who owns it, who revises it?
  • adapting the idea of design patterns to writing; start a doc with an architecture. examples:
    • tell a story linear timeline (walkthrough)
    • paint a picture spapshot (introduce feature/tool)
    • reference introduce one at a time and describe
    • theme + situation idea and use cases (intro to concept)
    • drill down general -> specific
    • level up simple to complex (getting started.doc)
  • Errors/name your variables
    • Undefined 'it'
    • No ownership (avoid magic. [that doesn't mean no django])
    • Vague terms (don't use generic tech terms)
    • Unnamed ideas
  • Idea of refactoring vs editing

###Open Source Docs the Hard Way - Anne Gentle

  • Seems like the 80/20 'principle' (editorial scarequotes there); a small segment of contributers put in the bulk of the work.
  • Book sprints!
    • OpenStack flew in a whole bunch of writing volunteers and wrote the OpenStack Operations Guide, which wound up being published by O'Reilly.
  • OSS works; open source docs can work, too.

###Documenting Domain Specific Knowledge - Alex Gaynor

  • Think about who the documentation is for.
  • Audience – set of knowledge people will come with.
  • Document according to audiences; e.g. new users and experts
  • Thinks that straight line docs are best; optional stuff can be linked. Trim the fat, it distracts.
  • No assumptions: e.g. no jargon.
  • It's fine to be prescriptive. You're an expert; share that expertise by informing the reader as to best practices. (Drowning readers in options is often, IMHO, a form of showbloating.)
  • Addressing use cases is great. Finding out what use cases the community wants/needs is probably difficult if you don't have a strong community. Good argument for not treating your community like minions/rubes, btw.
  • If users have to go to Stack Overflow to figure out your docs, your docs fail.
  • Learners often don't know what they don't know. The docs need to inform users of everything they ought to know.
  • Users asking 'How do I X?' is feedback on docs.

###Graphical Explanations - Geoffrey Grosenbach

  • Using graphics in your documentation helps docs to be consumed in different ways (e.g. flip/skim/read).
  • Envisioning Information Edward Tufte - check out his ideas about graphics.
  • Information Dashboard Design Stephen Few
  • Type/typography
  • Color
  • Explanatory tools - making a list of ways of explaining things
    • side-by-side
    • good/better/best
    • timeline

###TechDocs at Twitter: Creating the Culture of Documentation - Simeon Franklin & Marko Gargenta

  • What does it mean to do technical documentation (engineer to engineer)?
  • Treat docs like code; written by engineers
  • Wikis are messy. Not the best solution
  • If developers are writing code, use the existing code workflow.
    • Check in! Version, check, merge!
    • Harder for the writers, but much easier for the developers.
  • ReStructuredText
  • Made a plan. e.g. DocDay -> Templates -> DocBird (platform)
  • Thinking of documentation as a platform opens up all sort of cool possibilities.