Doing talk timing this morning while writing notes, so forgive me if I don’t get everything but videos and slides should be up later after the conference is done.
Kenzie Woodbridge – Everyone’s a player (in a mid-90s MUD)
There are many ways to look at situations. Changing the way you look at a situation can provide new strategies and solutions.
Context: wear many hats, work at BCIT, many students, programs, centralized IT, have many different software including some in-house and open source projects, so documentation needs are very varied.
Documentation exists because there are people that have needs: different role, focus, technical skills, ways of working.
Types
MUD: multi-user dungeon, text only multi-user online games. Types of players based on 2 axes: interact – act; players – world. interact/players: socializer, interact/world: explorer, world/act: achiever, players/act: killer. (Caveat: obviously simplistic model.)
Implications for documentation: different types of documentation can emphasize different types of players. Change axes: interact – act; users – technology. Explorer, Socializer, Achiever, Killer (gatekeeper).
- Socializer: natural documentor being user centred, may need support to start
- Explorer: motivated by knowledge, natural anti-documentor; doesn’t want to tell people how to do something.
- Achiever: inconsistent documentor, depends on what they are trying to achieve, and opportunist
- Killer: inconsistent documentor, element of destructive chaos, don’t want to document because it allows others to avoid power plays
Solutions and Strategies
- Socializer: need support. expect to provide templates, assist with publishing, impose a structure and organization, advocate for them to others, work to include them where they are excluded, give them public kudos
- Explorer: have to extract somehow, reframing strategies, documentation shows off expertise, keeps icky users away, another thing to have knowledge of, expect to reduce barriers (provide templates), rewrite docs for audience, help enforce expectation to look at docs first
- Achiever: gamification, to motivate: post doc writing/review stats, make doc authors visible (but maybe not to public), advocate for docs as critical success criteria in projects, be available on short notice, provide and enforce templates, publicly thank them
- Killer: self-protection strategies, keep discussions public, document everything (ironically), have it in writing, engage explorers in the struggle, go forward: treat agreements like agreements, follow up, expect but do not tolerate delays or power plays
Jodie Putrino – Treating documentation like code: a practical account
Was hired to help with project. The idea was to have the docs in the same repo, with same model of CI and testing.
We want to develop the documentation with the code.
Why?
- Keep it in lock step with dev process.
- Keeps you thinking about the docs.
- Let subject matter experts share their knowledge when it’s fresh.
- Keep together docs up to date with features.
How?
Difficult to find publicly available information to do this process. Nothing outlined best practices. How it happened:
- Choose the right tools
- Automate: automate what you can to focus on the things you can’t
- Collaborate: worked out best way for everyone to contribute to project
- define, then design
- Adapt
Write (RST, some markdown) and review (as needed) are the only manual process, push up to github, everything else is automated (test, deploy). Testing: using TravisCI, all running the same tests, docker container for all dependencies including Sphinx toolset. Deloy: use Travis CI script to securely store AWS credentials, pull docker image, run test scripts in container, deploy to AWS S3 bucket.
One docs website to rule them all: many projects from many git repos get integrated to one site. Eventually have API documentation. Audience differs though most internal sales, and support, sometimes developers.
Will use workflow in the future even in projects without technical writer. Now are all doc writers. Important to have realistic expectations. Everyone contribute in a way that is appropriate to their skillset.
Some of the questions had: Who are our users? How do they use/find documentation? What kinds of docs do we want/need to publish? How do we handle versioning? How do we track usage? When do we publish? Can we get user feedback? Versioning: only one doc website, so have different versioning number and release schedule.
The process is not the thing. It’s always worth asking, do we own the process or does the process own us?
The information you need is clearly provided in the documentation. Provide the best documentation you can to users as possible when they need it.
Sam Faktorovich – Interviewing and hiring technical writers: the Siberian way
Background: programmer first, project manager, then technical writer. Company went from none to one technical writer.
Why set up internal documentation? To improve the speed of knowledge transfer inside the company.
Integration/architecture docs: How is the component built? Why was it built this way? Why should all this matter to you?
Necessary skills for technical writers:
- technical stuff:
- CS fundamentals: algorithms, design patterns…
- Linux specifics: processes, threads, IPC, networking…
- Knowledge of C++: reading code is important
- capability and willingness to write documentation
Then went looking for more technical writers. Unfortunately, very few technical writers in the city. Decided prior experience as a technical writer should not be required. Found people with one area and teach the other area, looked for either technical background or good writing skills, and gave pre-interview writing test.
Results: 120 candidates, 40 interviews, 6 hires, 4 persons still working in 2017
Of 120 candidates: 2 candidates had both sides; 60 technical skills, 2 hires, but very difficult to teach them to write well; 60 candidates textual skills
Knowing how to write well =! knowing how to teach others to write well.
Teaching technical things to non-tech people: CS fundamentals turned out to be teachable! lots of teaching materials publicly available, fundamental technical knowledge is easily transferable. 2 month crash course did the job.
Teaching a good writer to code is easier than teaching a good coder to write.
Pre-interview assignment task: write a medium sized (1-2 pages) text describing a complex technical topic: topic defined by company, 2-3 weeks to complete task, use any information sources they like. Should not mimic typical day-to-day documents, show candidate’s capability to explain complex things.
Good doc is like an educational lesson, rather than telling what someone to do.
The documentation must teach. You should think of your documentation as a lesson (or series of lessons) because that’s what it is.
Example topics: explain difference between HTTP and HTTPS to non-technical owner of an e-commerce website. Difference between UTF-8 and UTF-16 to a programmer who is unaware of Unicode concepts.
Other approaches:
- recruit own developers to be technical writers? No.
- Grow the job market itself? Yes!
Growing the job market:
- technical writing class in one of the local universities
- public lectures promoting the profession of a technical writer
- technical writing bootcamps: several skills
- corporate consulting on setting up documentation departments/processes
- 2013 zero job openings; 2017: 6-10 technical writer job openings per month
Summary
- “technical” technical writiers are rare: hire good writing talent first
- evaluate the writing talent by checking how they explain things
- teaching a good writer to code is easier than teaching a good coder to write
- grow the market: it’s beneficial for everyone
Ingrid Towey – The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization
Red hat is built around open source software. What does it mean to be open? Jim Whitehurst wrote a book on it, and did AMA.
Open decision framework: transparent, inclusive, customer-centric. Can be difficult at times: 100+ people just in one group, 4 continents, 11 writing standards initiatives
Crowdsourcing is naturally open source: take a group of people, and outsource to the group of people. The crowd is smarter than the intelligence of a single person. Crowdsourcing works because had external structure, diverse group of experts, independent thinkers (no group think), someone to aggregate.
All of us together are smarter than any one of us alone.
Experiment: Crowdsourcing minimalism. Minimalist critique. Group in NA had the most success with the same characteristics. Minimalism in writing: getting back to the fundamentals, focus on what the customer wants and needs to do. Characteristics: customer focus, action oriented (avoid passive voice), findability (use the best possible location), concrete words, good and clear titles and headings, no fluff (nothing superficial), good error recognition (incorporate troubleshooting).
Meeting process: review minimalism principles, assign notetaker, review doc for each minimalism guideline if met.
consolidation process: analyze and consolidate feedback, share doc with group for corrections, meet with author to share feedback.
Try this! The method can work anywhere.
Sarah Hersh – Start with the tasks, not the endpoints: A task-oriented approach to API documentation
NPR = National Public Radio. NPR One developer centre enables work with developers to extend the NPR One experience to new platforms and new audiences.
Task oriented documentation: ask not what each endpoint can do, ask what the user as the developer can do with these API services.
In practice: before you start writing, discuss these key guiding questions with your team:
- Why are we making this service publicly available? What do we hope developers will accomplish?
- Why would a developer want to access this API? What tasks might they want to accomplish?
- Do these objectives align? How do our goals and priorities overlap with those of our users?
Define developer personas by their goals, behaviours, and attitudes. Work with team to determine which should be prioritized. Conduct interviews with partner developers to validate assumptions and identify tasks that are comment to each type.
identify and prioritize tasks: compile list of common tasks, analyze logs, refer back to goals and priorities, list subtasks to document and map to ticket.
Takeaways from site redesign:
- highlight prioritized tasks,
- edit for task accomplishment,
- present information in order of operations,
- keep navigation shallow, but add linked checklists and inline/related links
- still have reference docs, still valuable
- a lot of positive feedback; included developers and hobbyists-types; less support tickets
Benefits
- efficient scoping and onboarding
- rapid prototyping and lower cost to explore opportunities
- faster turnaround on QA and test build feedback
- decreased time burden on team during app verification process
- higher quality user experience for listeners cross platforms
Applying for other APIs. More narrative documentation. Thinking outside the box: using task-oriented approach with newsletter, pre-launch app checklist, surveys, emails, conference calls, internal documentation (more cohesive and consistent with same process).
Break
