├── .aider.chat.history.md ├── .aider.input.history ├── drafts ├── TypesOfMesses.rst ├── IdentifyYourSMEs.md ├── more_topics.md ├── TopicPatterns.rst └── AuthoringToolsChanging.md ├── YourPlan.md ├── Resources.md ├── .github └── workflows │ └── build.ym; ├── IdentifyYourAudiences.md ├── InheritingAMess.md ├── index.rst ├── CreateTechnicalGlossary.md ├── Expectations.md ├── AuditExistingContent.md ├── IdentifyYourStakeholders.md ├── TechnicalProductSummary.md ├── WorkingWithYourManager.md ├── CreateAStyleGuide.md ├── ContentReviewProcedures.md ├── QuickWins.md ├── GettingEveryoneToWrite.md ├── TelecommutingTips.md ├── StaticSiteGenerators.md ├── README.md ├── StyleGuides.md ├── TestingDocs.md ├── AuthoringTools.md └── DocTeamProcedures.md /.aider.chat.history.md: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /.aider.input.history: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /drafts/TypesOfMesses.rst: -------------------------------------------------------------------------------- 1 | What types of messes might you find? How can you address specific issues in your documentation? 2 | 3 | * No Code Comments 4 | * No decision history 5 | * No architectural information 6 | * No build process documentation 7 | 8 | -------------------------------------------------------------------------------- /drafts/IdentifyYourSMEs.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | Identify your SMEs and Stake Holders 4 | 5 | 6 | Starting notes: 7 | --------------- 8 | * Identify subject matter experts. Cultivate relationships with SMEs, who will help write and review your docs. 9 | * Finding the key stakeholders. Which internal stakeholders can be your ally? See "Identify subject matter experts". 10 | 11 | 12 | Hack-a-thon content: 13 | -------------------- 14 | -------------------------------------------------------------------------------- /YourPlan.md: -------------------------------------------------------------------------------- 1 | # Your Doc Plan or Backlog 2 | 3 | 4 | ## You need a Plan 5 | 6 | You need a plan to get you from point A to point B, but also for the following purposes: 7 | 8 | * To show your boss the path ahead 9 | * To prioritize the numerous tasks ahead of you 10 | * To communicate with Key Stakeholders to ensure that your tasks aligned with the Company's needs and that you have enough context to get started. 11 | 12 | 13 | 14 | 15 | ## Be Ready to Change Course 16 | 17 | Plan just enough that you know what you need to do, but not so much that it would be painful to change the plan if something unexpected happens. 18 | -------------------------------------------------------------------------------- /Resources.md: -------------------------------------------------------------------------------- 1 | 2 | # Resources 3 | 4 | 5 | Technical writing resources 6 | *************************** 7 | 8 | If you don't have fabulously smart writing colleagues as a resource, consider the following: 9 | * http://www.hemingwayapp.com/ 10 | * Grammarly, https://www.grammarly.com/ 11 | * Chicago Manual of Style, http://www.chicagomanualofstyle.org/home.html 12 | * Microsoft Manual of Style, Microsoft Corporation 13 | * Purdue University Writing Lab, https://owl.english.purdue.edu/owl/section/4/16/ 14 | * I'd rather be writing, http://idratherbewriting.com/ 15 | * (book) The Elements of Style (aka "Strunk & White"), by E. B. White and William Strunk Jr. 16 | -------------------------------------------------------------------------------- /drafts/more_topics.md: -------------------------------------------------------------------------------- 1 | Here are some more suggestions for topics that could be added to this book: 2 | 3 | * Taking part in the Agile process 4 | * Should you start by fixing old copy or writing new? How to decide? 5 | * Take some points from Neal Kaplan's "Triage" presentation at WTD Portland '18. 6 | * Gather whatever there is of existing content (internal/external, Wiki entries, scribbles on napkins...) 7 | * Vet that content for its quality and usableness. Do this very fast. 8 | * Evaluate what kinds of documentation you can deliver, weighing business value and level of effort. 9 | * Make a rough plan. A rough plan now is better than a perfect plan later 10 | * etc. 11 | -------------------------------------------------------------------------------- /drafts/TopicPatterns.rst: -------------------------------------------------------------------------------- 1 | 2 | 3 | **************************** 4 | Topic patterns and templates 5 | ***************************** 6 | 7 | ================================================================= 8 | How to swim in the deep water - A lone writer’s guide to survival 9 | ================================================================== 10 | 11 | Starting notes: 12 | --------------- 13 | 14 | * What topic patterns (or templates) would be useful to have to give to developers to help draft documentation? 15 | * What are the standards to use for topic patterns? 16 | 17 | 18 | Hack-a-thon content: 19 | -------------------- 20 | -------------------------------------------------------------------------------- /drafts/AuthoringToolsChanging.md: -------------------------------------------------------------------------------- 1 | # Authoring tools - changing 2 | 3 | 4 | ## How to swim in the deep water - A lone writer’s guide to survival 5 | 6 | 7 | Starting notes: 8 | --------------- 9 | 10 | * Change an authoring tools. Do you keep the existing tool (if there is one) or change the tool? Will changing the tool impact developers contributing to the docs? Suppose you use something like Markdown and the developers use that to help create documentation. But then you change the tool to something that developers don't know and so they contribute less to the documentation. How to handle this? 11 | * Cost of changing tools. When does the long term benefit outweigh the short term transition? Not just the expense of the tool, but the impact on converting over to the new tool. 12 | 13 | Hack-a-thon content: 14 | --------------------- 15 | 16 | Hack-a-thon content: 17 | Test file 3/15/18 18 | -------------------------------------------------------------------------------- /.github/workflows/build.ym;: -------------------------------------------------------------------------------- 1 | # This is a basic workflow to help you get started with Actions 2 | 3 | name: CI 4 | 5 | # Controls when the workflow will run 6 | on: 7 | # Triggers the workflow on push or pull request events but only for the "master" branch 8 | push: 9 | branches: [ "master" ] 10 | pull_request: 11 | branches: [ "master" ] 12 | workflow_dispatch: 13 | 14 | # A workflow run is made up of one or more jobs that can run sequentially or in parallel 15 | jobs: 16 | # This workflow contains a single job called "build" 17 | build: 18 | runs-on: ubuntu-latest 19 | needs: clone 20 | steps: 21 | - name: clone repo 22 | uses: actions/checkout@v4 23 | 24 | - name: build site 25 | uses: ammaraskar/sphinx-action@master 26 | with: 27 | docs-folder: "docs/" 28 | build-command: "sphinx-build -b html . _build" 29 | 30 | 31 | -------------------------------------------------------------------------------- /IdentifyYourAudiences.md: -------------------------------------------------------------------------------- 1 | 2 | # Identify Your Audiences 3 | 4 | 5 | 6 | ## Six Levels of Experience: 7 | 8 | 9 | ================= ====================================== ============================== 10 | Skill Level Experience Needs 11 | ================= ====================================== ============================== 12 | Master Creates new traditions Core Concepts 13 | Expert Intuitive grasp of many situations Patterns 14 | Proficient Zeros in accurately on important areas Maxims 15 | Competent Understands standard practices Guidance on salient features 16 | Advanced beginner Recognizes recurring aspects Rules with some context 17 | Beginner Little to none Context-free rules 18 | ================= ====================================== ============================== 19 | -------------------------------------------------------------------------------- /InheritingAMess.md: -------------------------------------------------------------------------------- 1 | 2 | # Inheriting a mess 3 | 4 | 5 | 6 | Suppose you inherited a mess like this: 7 | 8 | * flat, unrefined knowledge base 9 | 10 | * Overlapping content 11 | 12 | * Redundant knowledge 13 | 14 | * 1 person team 15 | 16 | Think about these: 17 | 18 | * Try to understand what the goals/priorities were of previous solutions, versus what goals you’re trying to accomplish now. 19 | 20 | * Keep your priorities in mind when determining next steps. 21 | 22 | * Make sure the solution is scalable; once you have a better solution, other teams will want in. 23 | 24 | * If your audience is internal and cross-department, consider whether gating content with permissions will solve existing problems. 25 | 26 | * How much content will change? 27 | 28 | * Define your hierarchy 29 | 30 | * Keep the audience in mind 31 | 32 | * Organize docs by function/purpose/types 33 | 34 | * Depending on whether you’re inheriting internal or external-facing content, consider breaking down content by either product/category or per-department. Using both will get messy. 35 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | 2 | 3 | ================== 4 | Lone Writers Guide 5 | ================== 6 | 7 | .. toctree:: 8 | :maxdepth: 2 9 | :hidden: 10 | 11 | /AuditExistingContent 12 | /AuthoringTools 13 | 14 | If you work alone, this guide will provide helpful advice from others who have walked the same road. 15 | 16 | 17 | 18 | People 19 | ****** 20 | * :doc:`Expectations` 21 | * :doc:`WorkingWithYourManager` 22 | * :doc:`IdentifyYourAudiences` 23 | * :doc:`IdentifyYourStakeholders` 24 | * :doc:`GettingEveryoneToWrite` 25 | 26 | Processes 27 | ********* 28 | * :doc:`ContentReviewProcedures` 29 | * :doc:`DocTeamProcedures` 30 | * :doc:`TestingDocs` 31 | * :doc:`TelecommutingTips` 32 | 33 | Assessing Your Company's Docs 34 | ***************************** 35 | * :doc:`InheritingAMess` 36 | * :doc:`AuditExistingContent` 37 | * :doc:`TechnicalProductSummary` 38 | * :doc:`CreateTechnicalGlossary` 39 | 40 | Your Plan for Action 41 | ********************* 42 | * :doc:`QuickWins` 43 | * :doc:`YourPlan` 44 | 45 | Other Learning Resources 46 | ************************ 47 | * :doc:`Resources` 48 | -------------------------------------------------------------------------------- /CreateTechnicalGlossary.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Creating a Technical Glossary 4 | 5 | 6 | You’re in a new situation: 7 | * Start working on a glossary right away. You're a new person with new eyes and ears: take advantage of this while it lasts. 8 | * Look for glossaries that others have created. 9 | * Terminology: what is industry standard that does not belong in our glossary? Or other constraints (3rd-party 10 | product’s terminology) 11 | 12 | * You’re likely to be the person who finds discrepancies across teams or terms 13 | 14 | * Hopefully part of the glossary can be customer-facing so that you can show that it’s worthwhile to be spending your time on this 15 | 16 | * How you write the definitions in your glossary: write carefully so you know what knowledge to assume the audience has. 17 | 18 | * Sources/SMEs for your glossary: YOU and your fresh eyes as you respond to practically anything you have contact with in your first days. 19 | 20 | * Once you have a glossary made, use the glossary to *control* terminology (programmatically ideally, but also culturally). Get people to agree on terminology. 21 | 22 | * Tease out internal versus external names 23 | 24 | * Think about naming conventions for APIs 25 | 26 | * Write definitions carefully, keeping in mind the audience's level of familiarity with technology 27 | 28 | * Aim for wide distribution: Sales, Marketing, Support, Professional or Managed Services, Dev, UX 29 | 30 | * You want your glossary to be the “gold file” - the canonical document of record 31 | -------------------------------------------------------------------------------- /Expectations.md: -------------------------------------------------------------------------------- 1 | # Setting expectations 2 | 3 | 4 | 5 | As the lone technical writer at your company, first determine the docs that you are tasked with writing. 6 | Sometimes, the job specification and description duties do not align with what you are tasked to write at your company. 7 | Early on, be sure to obtain (more than likely create) a list of all documentation that you are creating/reviewing/publishing. 8 | 9 | * Identify documentation: 10 | 11 | - By audience (external vs internal) 12 | 13 | - By department (Support, Implementations, Marketing, Developers, etc) 14 | 15 | * Documentation Examples: 16 | 17 | - Release notes 18 | 19 | - Changelogs 20 | 21 | - Product Documentation 22 | 23 | - User Manuals 24 | 25 | - How-tos 26 | 27 | - Quick-start Guides 28 | 29 | - White papers 30 | 31 | - Slide decks 32 | 33 | * Determine who your SMEs and stakeholders are for your docs. 34 | 35 | Deadlines and timelines 36 | Work backwards from due dates. Most external documentation deadlines are tied to customer/client contracts (service-level agreements). For example, release notes are contractually required to be sent to clients one week before a release. 37 | 38 | Set deadlines for documentation draft material from SMEs, review sessions, and final reviews. Effective collaboration and communication, especially when SMEs are in different offices or remote, is essential for meeting deadlines. 39 | 40 | Avoiding burnout and suckerville 41 | Learn to say NO! (with tact, of course). 42 | Set realistic expectations for a lone writer workload. 43 | -------------------------------------------------------------------------------- /AuditExistingContent.md: -------------------------------------------------------------------------------- 1 | # Audit existing content 2 | 3 | 4 | ## How to swim in the deep water - A lone writer’s guide to survival 5 | 6 | When you inherit docs from a writer who has left the company, it's important to know what you have to work with. Consider: 7 | 8 | * How are the docs organized? 9 | * Are there gaps in the content? 10 | * Have customers complained about missing information? 11 | 12 | Conducting a high-level audit will give you the answers to these questions. 13 | 14 | Start by looking at the docs from an organizational perspective. Is the content organized in a logical order? Can you identify any gaps in the content? Don’t get wrapped up in the details. 15 | 16 | 17 | Next, go to your manager and the Key Stakeholders. Interview them and ask them about the documentation. Show them the content online and ask them: 18 | 19 | * Does the organization seem logical? 20 | * Do they see any gaps or missing information? 21 | * Has anyone has complained that there is missing or confusing information? 22 | 23 | If you can interview 1-2 key customers, ask them the same questions. 24 | 25 | All of these interviews will give you a better picture of the state of the docs, and metrics to explain the status of the docs to your manager. 26 | 27 | Summarize the information that you gather and try to prioritize the list of things to improve. If you can, try to estimate how long you think it will take to make the improvements. Then, multiply that estimate by 3. Yes, 3. It always, always takes longer than you think it will. If it is a real mess, multiply by 4. 28 | -------------------------------------------------------------------------------- /IdentifyYourStakeholders.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Identify your Stakeholders 4 | 5 | 6 | 7 | Why this is important: 8 | 9 | * The stakeholders know the customers well; they know the business goals. They can help you prioritize. 10 | * If you design something without taking into account what the stakeholders find to be important, the time will come they’ll kill it 11 | * You can’t necessarily go by job titles, especially in a young org. 12 | * Not necessarily the dev group 13 | * Not necessarily your best reviewers 14 | 15 | How do you figure this out? (stakeholders for the doc) 16 | 17 | * Find out who cares 18 | * Talk to people who’ve been there a long time 19 | * Spread around groups: PM, QA, Mktg, UX, Support, DevX, Professional Services. Cast your net widely. Listen for who’s got contact with customers; who’s got visibility into the direction of the product. 20 | * Who writes the specs? 21 | * Outside the company: Who’s making purchase decisions? 22 | 23 | What questions do you ask? 24 | 25 | * What’s your biggest pain point that docs can help with? 26 | * What’s the most important goal the company has this year? 27 | * What do you mean when you say “docs”? (e.g., behind login? Internal versus external? File format? Code snippets? KB?) 28 | * Include boilerplate elements such as Known issues and pain points. 29 | 30 | 31 | What if you do not know where to start? 32 | 33 | Create nodes for everyone involved within the company (especially if the company is small) 34 | Draw connections (from prior experience) to see who often interacts with who 35 | Understand which nodes would be directly affected by your project. 36 | Ask yourself how the changes would impact that node, and what tertiary effects a choice would have. 37 | Perhaps create a list of a writing's utility. How would these people be affected by your decision? 38 | -------------------------------------------------------------------------------- /TechnicalProductSummary.md: -------------------------------------------------------------------------------- 1 | # Technical product summary 2 | 3 | 4 | When you're working on creating a product summary for a technical product, your first step is to brainstorm your plan. 5 | 6 | You should prepare an outline that answers the 5 W's. 7 | 8 | * Who is your audience? Who will you interview to learn about the product? Who will be reviewing the content? 9 | 10 | * What should the summary cover? 11 | 12 | * When is the writing deadline? What does the roadmap timeline look like in order to help you meet the writing deadline? 13 | 14 | * Why is the summary needed? 15 | 16 | * Where is the summary going to live? How will your audience find the content? 17 | 18 | By asking these question, you create the scope for your writing project. 19 | 20 | Next, outline what information should be captured in your summary. If there is existing documentation, such as design docs, guides, etc., read or glimpse through those documents to get a sense of the product. You can also use Google search to gain background and introductory information on the subject area. List key words and key concepts the reader might need to know before they start reading the summary. 21 | 22 | Then, think about the questions to ask your subject matter expert (SME). Plan an outline to strategize the structure of your summary, and phrase your interview questions to help you fill content into the structure of your doc. 23 | 24 | Now that you have done your research and have interviewed your SME, you should have enough information to get started with writing the summary. Start by introducing the topic. Think about the purpose of the product and the value it brings to its users. Evangelize the product. If the technical product summary is intended for a technical audience, describe the basic concepts or prerequisites that the reader might need to know before they jump into writing. Use your outline to structure your summary. Feel free to mention similar products, the competitors, or what sets this product apart from other products. Use visuals if it helps the reader understand the product. 25 | 26 | If you are stuck, ask yourself, "By the end of summary, what should the reader know?" When you're writing a summary, your goal is to provide the reader a high-level summary of the topic, rather than getting down to the nitty-gritty of the product. The summary doc is meant to be an introduction of the product. 27 | 28 | Once you feel that your work accomplishes the objective of the summary, close off the summary by directing the user to more information. You might want to summarize how to get started to use the product, how to access the product, or learn more about the product. Finally, create a title that describes what the summary is about. 29 | -------------------------------------------------------------------------------- /WorkingWithYourManager.md: -------------------------------------------------------------------------------- 1 | # Working with your manager: 2 | 3 | 4 | How to Establish A Positive Relationship from the Start 5 | 6 | * Ask a lot of questions 7 | * Have them define what they value in "good writing" 8 | * Ask someone how they see your role working, including how you will function, who you will talk to, and what you will deliver 9 | * Tread lightly when performing an extensive edit or overhaul right out of the gate 10 | * Establish your own competency and knowledge early on (this can be especially important for female-identifying writers) 11 | * Ask for the information you want and need, instead of being general 12 | * Do your best to identify the correct person to ask a question - be intentional 13 | * Find an ally, even outside of your organizational group 14 | * There's a need for written materials that's never going to go away 15 | * Cite studies that prove the value of documentation 16 | * Talk about your own documentation successes, as well as those of others 17 | * Talk to your support or services organization, someone that talks to customers. They should be your ally. Develop this relationship. 18 | * Explain what happens when you _don't_ have documentation that is that good 19 | * Utilize analytics - wouldn't you want a website to be good if it has so many views? 20 | * Lone writers can easily bring things to light - they might later think, "how could I have missed this?" (After this happens, reassure them!) 21 | * Remind everyone that you are there to represent the users' needs. 22 | * ACCEPT CRITICISM 23 | * Do good work in ways that others can see. 24 | * Market yourself as a service within your organization. 25 | * To show the value of your own best practices, tell them that these principles exist, and you're improving their content. Then they'll see how the content improved and recognize it. 26 | * Developers will see what you've done with their work, and then start to imitate you! They'll see what it means to apply standards. 27 | * Have genuine enthusiasm for the work of developers, and your own work as well 28 | 29 | 30 | How to get quality doc reviews from a non-writing-savvy manager: 31 | 32 | Frequently, managers who haven't managed a writer before do not know the type of feedback that we need. For example, a manager might lightly copyedit your work, when what you truly need is a technical review, or their thoughts about a new structure. Here are some suggestions for getting quality docs reviews: 33 | 34 | * Create a mini-training on how to review documentation 35 | * Specifically call out the "type" of review that you're looking for, be it technical, developmental, etc. 36 | * Reinforce good reviewing behaviors 37 | * Create a review checklist of what you'd like them to read for 38 | -------------------------------------------------------------------------------- /CreateAStyleGuide.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Create a Style Guide 4 | 5 | 6 | 7 | ## Getting Started 8 | 9 | when you're ready to start a company style guide, here are some general ideas about how to do it. 10 | 11 | * Choose an external style guide (Microsoft Manual of Style, Chicago, etc.) 12 | * Company product names, including correct trademark attribution, capitalization, and any allowed short forms. 13 | * English, British, Australian, English? 14 | * Style 15 | 16 | * Present tense 17 | * Second person 18 | * Active voice 19 | * Conversational tone 20 | * Do not use courtesies (please, thank you, and so on) 21 | * Decide whether to use contractions 22 | 23 | * Title vs. sentence case for: 24 | 25 | * Headings 26 | * Figure captions 27 | * Table titles 28 | * Table column headings 29 | 30 | * Consider global and ESL readers 31 | 32 | * One word, one meaning 33 | * Do not use colloquialisms 34 | * Do not use idioms 35 | 36 | * Parallelism in: 37 | 38 | * Presenting all tasks the same way (e.g., start with a prerequisite, then numbered steps, then a postreq/what to do next) 39 | * Bullet lists - Within a given list, all bullets should be phrases or sentences. (Note that this Style Guide doesn’t follow this recommendation. At times, such as for internal use only, it’s not worth the time to reach for perfection.) 40 | * Same order of info/syntax/examples for all reference sections 41 | 42 | * Basic graphics/screenshot guidelines: 43 | 44 | * Source tool (e.g., Snagit, Visio, Omnigraffle, etc.) 45 | * Output format (SVG, PNG, etc.) 46 | * Callout style (wording and line color/width/style) 47 | 48 | * Legalese page - get the Legal department to sign off: 49 | 50 | * Third party references 51 | * Disclaimers (use product at your own risk) 52 | * Proprietary/confidentiality statements 53 | * Copyright 54 | 55 | * Progressive disclosure 56 | 57 | * One idea per paragraph 58 | * Paragraphs follow each other in a logical order 59 | 60 | Copyedit checklist: 61 | ==================== 62 | 63 | * spell check 64 | 65 | * punctuation: 66 | 67 | ** check for double spaces 68 | 69 | ** if you used the following correctly: 70 | 71 | *** .. extra period - check for and delete 72 | 73 | *** , comma 74 | 75 | *** ; semi-colon 76 | 77 | *** : colon 78 | 79 | *** () parenthesis 80 | 81 | *** ' apostrophe 82 | 83 | * subject/verb agreement 84 | 85 | * numerals 86 | 87 | * fonts and capitalization 88 | 89 | * headings - logical and in order 90 | 91 | * tables - are table formats consistent? 92 | 93 | * links - correct and working 94 | 95 | * headers and footers, if you're using 96 | 97 | * notes & peripheral data - footnotes, endnotes, appendixe 98 | -------------------------------------------------------------------------------- /ContentReviewProcedures.md: -------------------------------------------------------------------------------- 1 | 2 | # Getting docs reviewed 3 | 4 | 5 | 6 | ## How to swim in the deep water - A lone writer’s guide to survival 7 | 8 | 9 | Create a content review process to: 10 | 11 | * facilitate consistency and accuracy across the docs (e.g., style guidelines, topic patterns) 12 | * communicate expectations, goals, and progress with stakeholders 13 | * clarify user stories, use cases, and learning objectives 14 | * coordinate technical reviews with SMEs 15 | 16 | ### Who should review the docs? 17 | 18 | 19 | As the lone writer, you should be the first and last person to review content before updating the docs. To confirm the accuracy of the content, set up a technical review procedure for the SMEs with knowledge of the content that you're adding or modifying. Depending on the content that you're adding or modifying, the SMEs could be people in engineering, QA, customer support, and/or marketing. You'll also want to establish a review procedure with PMs to clarify user stories, use cases, and expectations for the docs. 20 | 21 | By the end of the content review process, the following people will have reviewed the docs: 22 | 23 | * you 24 | * PMs 25 | * SMEs 26 | 27 | ### Creating a content review process 28 | 29 | Below is an example content review process. You may need to modify these steps, or the order in which you carry out each step, according to your particular environment. Keep in mind that you need to learn and adapt to the processes that SMEs and other stakeholders already have in place when you begin working as a lone writer. 30 | 31 | This procedure begins after the initial draft of a doc update: 32 | 33 | 1. Evaluate the doc for consistency and accuracy according to style guidelines and topic patterns. 34 | 35 | 2. Think about use cases and learning objectives for the content that you're documenting. Are these things defined well and explained properly? Can improvements be made? If you have any remaining questions, reach out to PMs to clarify and confirm objectives for the doc; SMEs can also provide valuable input to clarify user goals and learning objectives for the content that you're documenting here. 36 | 37 | 3. Review technical information. Do you have any questions? Will users have any questions? Does the information address the use case(s)? Is there too much information? After you attempt to answer these questions, reach out to the SMEs to schedule a technical review; address any remaining questions with the SMEs at this time. 38 | 39 | 4. Confirm that: 40 | 41 | * style guidelines and topic patterns are adhered to 42 | 43 | * user goals are clear and tasks are explained well 44 | 45 | * technical information is accurate 46 | 47 | Tips for reviewing content with SMEs and PMs 48 | 49 | Set a reasonable timeline for when the technical review is to be completed. Setting an agreed upon timeline helps keep things moving. 50 | -------------------------------------------------------------------------------- /QuickWins.md: -------------------------------------------------------------------------------- 1 | # Quick wins 2 | 3 | 4 | * Play politics (a little bit) 5 | 6 | It can't hurt to start to understand the politics or culture of the organization. Is this an Engineering-centric company, where Marketing is an afterthought? Or does the organization lead with Marketing? Is the Customer Success/Support function adequately staffed? 7 | 8 | Reaching out to principals in Marketing, Engineering, Support, Operations, etc. will help you establish and reinforce your role. When interviewing these principals, you may hear sentiments ranging from, "Boy am I glad you're here!" to "Who are you again? (And why are you wasting my time?)" 9 | 10 | Focusing your efforts on people who appreciate your role. You may have a broad charter or a narrow one; in either case, a quick win should be focused on teams that appreciate your presence. 11 | 12 | * Know your role 13 | 14 | What is the business case for your salary, and what have you been asked to do? Making sure that your wins align with the goals of the people who decided to hire you will reaffirm their decision and give you internal political capital. If you're a company's first-ever writer, why did your bosses decided writing needed to be one person's job, instead of a side task for several people? 15 | 16 | * Triage 17 | 18 | Seek out and embrace the triage process; your quick wins ought to be focused on "Severity 1 / Priority 1" issues. "Stopping the bleeding" is a quick win itself! Insist on attending bug triages (or backlog review, or any sort of formal prioritization process or bug scrub); doing so will quickly immerse you into the pain points of the product(s) and help you envision and prioritize first deliverables. 19 | 20 | (Note that the highest source of pain may be customer-facing or internal. You may not necessarily have a charter to produce internal documentation, but if you are alleviating pain, you could make a case for producing something quickly for an internal audience. See above.) 21 | 22 | * Hit the data 23 | 24 | Can you pull data on the pain points and priorities listed above? If you're working on customer-facing content, what are your most-visited articles, which articles are most likely to lead to submitted help tickets and which common searches have low click-through rates for top results? Grab some data before you start working. After you're done, check how the data has changed. There's nothing like showing your supervisors that writing well can have quantifiable results. 25 | 26 | * Use a "production values" strategy 27 | 28 | Filmmakers use the term "production values" to prioritize those things which will end up in the frames of the final cut that viewers will see. For example, the dollars spent on catering to feed the cast and crew -- while important and necessary -- aren't actually *seen* in the end-product by the consumers of the film. Therefore, it may be wiser to spend more money on costumes or makeup rather than sandwiches. If your charter is to prioritize end-user-facing documentation, you may want to be brutally honest about those deliverables that will provide the largest value for your time invested. 29 | 30 | * Don't be afraid to crow (a little) 31 | 32 | Once you've done something great, let people know! As the writer, you have a clear understanding of the value of your work. Don't be shy about sharing that with your colleagues. 33 | -------------------------------------------------------------------------------- /GettingEveryoneToWrite.md: -------------------------------------------------------------------------------- 1 | # Getting everyone to write 2 | 3 | 4 | As the lone writer, it is in your best interests (and key to your survival) to get others to help you write the documentation. How? You might get lucky and find someone who will give you all the info that you need. But more likely you will need to ask multiple people to piece together the complete info necessary for comprehensive documentation. 5 | 6 | * If your development team is using agile, request for documentation to be included in the definition of done requirements: 7 | 8 | ** Advantages: Direct access to the best authority - the original developers - while the information is still fresh in their minds and they are highly motivated (because they cannot complete their sprint without getting this done). 9 | 10 | 11 | * If your development team is using agile, request for documentation to be included in the definition of done requirements. 12 | 13 | ** Remember, the goal here is to capture information, not to produce full documentation. There is no need to require full documentation at this phase, bullet points will suffice. 14 | 15 | * Advantages: Direct access to the best authority - the original developers - while the information is still fresh in their minds and they are highly motivated (because they cannot complete their sprint without getting this done). 16 | 17 | * Remember, the goal here is to capture information, not to produce full documentation. There is no need to require full documentation at this phase, bullet points will suffice. 18 | 19 | * When a new feature is developed, check to see if there is a design document for the feature. If there isn't a design document, ask the developer (or the development team) to write up a summary of what the feature is. You might need to ask the developer some questions to ferret out more information, but it is a good practice to get them used to you asking for a description. The developers should get used to providing that type of information about the features that they work on. Ideally in a design document that is kept current. Additionally, if there is no design document, it is an opportunity for you to implement a new process that will help everyone - development, QA, marketing, project and program managers, and of course you (the doc team). See the "Quick Wins" section of this guide. 20 | 21 | * Check in with your SMEs. One or more of them should have information about the feature and should be able to help you out. 22 | 23 | * Ask QA. Presumably they are building test cases to test the feature. 24 | 25 | * Ask Marketing. Their perspective might be very different than development, SMEs, and QA. But is it good to know if their perspective of what is being developed matches with what the SMEs think, and what the development team has built. 26 | 27 | In a maneuver to help others with writing documents, it's important to reassure them that contributing to the writing process through explaining (perhaps generally) key or minor features to the project is essential for everyone's understanding. It may not be apparent to the others at first, but something as seemingly insignificant as a passing comment about this-or-that feature from one of the developers, a minor bug that QA is having issues with, or even a project manager's foggy idea of changing an existing feature; all of these can be expressed, logged, and re-read through documentation. 28 | 29 | -------------------------------------------------------------------------------- /TelecommutingTips.md: -------------------------------------------------------------------------------- 1 | # Telecommuting As a Lone Writer 2 | 3 | 4 | 5 | This document applies to both partial and full-time telecommuting. Note; Some of these tips also apply to lone writers who are onsite as well, depending on the way they write and make connections. 6 | 7 | Telecommuting has many benefits related to your personal life that everyone knows about. But working from home can be risky to your career development. I am going to explain how to make sure that telecommuting is a stepping stone to the career path you want, or longevity at your companay, rather than a step into obscurity. 8 | 9 | ## When You Start 10 | 11 | ### Plan to Go Onsite 12 | 13 | If by any chance, you can plan a week onsite shortly after you start the project, do this! It may not make sense to do this the very first week. You might want to wait until you've been working with the material for a week or so, so that you can plan whom you want to meet, and what you want to accomplish while you are onsite. Here are some reasons why: 14 | 15 | * Research has shown that it is easier to let someone go you don't see every day and you don't know. You can't change this job to be 100 percent onsite, but you can make sure that your coworkers and manager connect with you as a human. This will be so important, even if they only communicate with you in slack going forward. 16 | * While you are there during this week, note the times people arrive and leave, and the days and times when people tend to have meetings, when they tend to be out (lunch, breaks), when they tend to be be heads down. This will help you choose the right time to ping people going forward. It will also help you plan your breaks at times that will not cause alarm bells "Chris is never there when I ping her" (forgetting you are in another time zone!) While patterns aren't 100 percent predictable, they tend to evolve (eg., every Tuesday the Engineering team takes a long lunch) 17 | 18 | ## Hold a Launch Meeting Explicitly about Telecommuting With Direct Manager 19 | 20 | 21 | Have a meeting, online or in person, with your direct manager, and talk about these things: 22 | 23 | * Exactly what Success Means to this manager--Be sure they understand that you will have a ramp up time, if you expect to need one. If you are an onsite worker taking a few weeks to learn the system, they see you there. It's comforting. When you are offsite, they see that your paycheck is going out, but nothing tangible. Ask if there is something tangible you can create so that your manager can see progress. 24 | * Ask the manager if they are familiar with the tech writing/doc process. If not, explain the process you go through, how you will let the manager know when you have "heads-down" time for example. If you were onsite, you could have on headphones and the manager could see when you are deep diving into doc. You need to provide ways for the management to see you virtually. 25 | * Ask your manager if there is a time every day where it makes sense for you to take a lunch break. If you want to join a groups like Toastmasters, or a doc group, or something else like that, find out good times for you to attend (if you are in another time zone). Make sure your manager knows fairly set times when you are available. 26 | 27 | ## How to Keep from Going Crazy 28 | 29 | 30 | Your onsite coworkers are spending a bit of time every day chatting and connecting. If your company uses a tool like Slack, ask if you can set up some informal channels. 31 | -------------------------------------------------------------------------------- /StaticSiteGenerators.md: -------------------------------------------------------------------------------- 1 | 2 | # Static site generators 3 | 4 | 5 | 6 | A static site generator (SSG) is a tool that can convert a collection of markup files into web pages. Most SSGs include programs that host the resulting web site, but because the output doesn't depend on a specific hosting server, you have many options for deploying the content. Popular static site generators include Sphinx, Jekyll, and Asciidoctor. 7 | 8 | Advantages of SSGs: 9 | 10 | * You can leverage developer tools like Github. 11 | * You author content for SSGs in markup languages, which are non-proprietary, straightforward to read and learn, and easier to use than raw HTML. rST, Markdown, and AsciiDoc are examples of markup languages. 12 | * It's relatively easy to migrate from one static site generator to another. 13 | * There are lots of free, open source SSG tools. 14 | * SSGs use a workflow that developers are familiar with. 15 | 16 | One important advantage is that you can keep the documentation close to the code, sometimes even in the same repository as the code, and you can use the same workflow as for code. This encourages developers to keep documentation synchronized with the code. 17 | 18 | You should use a static site generator if: 19 | 20 | * You need to collaborate with developers. 21 | * You need something that's easy to set up and to maintain. 22 | * Your budget for infrastructure and tooling is low. 23 | 24 | Disadvantages: 25 | 26 | * SSGs have no content management system to manage things like: 27 | 28 | * Permissions - Access control isn’t built into most static site generators. If you don’t want your docs publicly accessible, access control is an additional expense on your time. 29 | * Versioning - Not all SSGs support deploying different versions of the same content at once. However, with some SSGs, you can name source control branches in a specific way to handle deploying different versions simultaneously. For example, you might name a branch "3.5" for the docs for version 3.5 of your content. Then, you can create a branch named 3.6 for the next version, and the SSG publishes both versions based on the content of the respective branches. 30 | 31 | * SSGs don't provide an editing tool or many of the editing features of other documentation authoring tools. 32 | 33 | WHICH ONE SHOULD I USE? 34 | 35 | You may want to choose a static site generator based on what markup language you work in and what programming language you or your colleagues have experience in. For example, you can write in rST to publish with Sphinx, which is written in Python. Or, you can write in Markdown to publish in Jekyll, which is written in Ruby. 36 | 37 | 38 | ## Popular tools 39 | 40 | 41 | * Sphinx 42 | * Jekyll 43 | * Hugo 44 | * AsciiDoctor 45 | * Mkdocs 46 | 47 | ## Getting a Grip on Static Site Generators 48 | 49 | 50 | In general, Sphinx parses rST, and Jekyll parses Markdown. 51 | 52 | There are also plugins out there to make Markdown work with Sphinx (like `recommonmark `_, or to make rST work with GitBook. 53 | 54 | All static site generators generate output in HTML, along with some that can also generate PDF, ePub, HTML inside JSON, and other formats. 55 | 56 | David Walsh wrote a `a great primer on static site generators `_ , especially if you’re interested in the plusses and minuses. The `Docs as Code book `_ and articles have a lot of great content around this as well. 57 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Lone Writer’s Guide 2 | 3 | The Lone Writer's Guide is one of the projects happening at [San Francisco Write the Docs.](https://www.meetup.com/Write-the-Docs-SF) 4 | 5 | * [Introduction](#introduction) 6 | * [Current Status](#current-status) 7 | * [Contents](#contents) 8 | * [Contributing](#contributing) 9 | 10 | ## Introduction 11 | 12 | If you're the new sole writer at a company and you've inherited a mess, what should you do fimd? What decisions (and trade-offs) must you address right away? What milestones should you hit in the fimd 30, 60, and 90 days? 13 | 14 | We started a guide for people who are thrown into the deep end to give them a plan for the fimd 90 days. This hackathon continues that work. 15 | 16 | Everyone has something to share, so join us for this project if you are (or have been) the sole writer at a company or a writer with lots of experience. 17 | 18 | ## Current Status 19 | 20 | This guide is in active development and has not yet been published. 21 | 22 | ## Contents 23 | 24 | We’re still working out how we want to organize what we’ve got so far, so this is very much a work in progress. If you see a better way to organize our contents, please [open an issue](https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide/issues/new) or a pull request! 25 | 26 | * [Audit Existing Content](AuditExistingContent.md) 27 | * [Authoring Tools](AuthoringTools.md) 28 | * [Authoring Tools Changing](AuthoringToolsChanging.md) 29 | * [Content Review Procedures](ContentReviewProcedures.md) 30 | * [Create a Style Guide](CreateAStyleGuide.md) 31 | * [Create Technical Glossary](CreateTechnicalGlossary.md) 32 | * [Doc Team Procedures](DocTeamProcedures.md) 33 | * [Expectations](Expectations.md) 34 | * [Getting Everyone To Write](GettingEveryoneToWrite.md) 35 | * [Identify Your Audiences](IdentifyYourAudiences.md) 36 | * [Identify Your Stakeholders](IdentifyYourStakeholders.md) 37 | * [Inheriting A Mess](InheritingAMess.md) 38 | * [Quick Wins](QuickWins.md) 39 | * [Resources](Resources.md) 40 | * [Static Site Generators](StaticSiteGenerators.md) 41 | * [Technical Product Summary](TechnicalProductSummary.md) 42 | * [Testing Docs](TestingDocs.md) 43 | * [Topic Patterns](TopicPatterns.md) 44 | * [Working With Your Manager](WorkingWithYourManager.md) 45 | 46 | ## Contributing 47 | 48 | You can contribute in several ways: 49 | 50 | * You can [edit these pages in your browser](#edit-in-your-browser-the-easy-way) 51 | * If you feel like a challenge, you can also Fork or clone the repo and work offline, but it's not necessary. There are some helpful instructions below, if you want to try that. 52 | * [Open an issue](https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide/issues/new) here in GitHub. This allows you to report a bug or make a suggestion without having to make the changes yourself. See the GitHub docs: [Creating an Issue](https://help.github.com/articles/creating-an-issue/). 53 | 54 | ## Before Contributing 55 | 56 | Before you contribute, please: 57 | 58 | * Review the docs to get an idea of what has been done so far. 59 | * If you already have a GitHub account, log in. Otherwise, [sign up](https://github.com/join). 60 | 61 | ## Edit in Your Browser the Easy Way 62 | 63 | 1. Use the edit button to start. 64 | 1. It's the one at the upper right with a symbol that looks like a pencil. 65 | 1. When finished, scroll down to click **Commit Changes**. 66 | 1. Click **Create Pull Request**. 67 | 68 | ## Edit in Your Favorite Text Editor 69 | 70 | If you want to do things the hard way, you can use the green button to clone the repo. That would allow you to work offline and in your favorite text editor. For help with Git, refer to the [official Git documentation](https://git-scm.com/doc). 71 | You can also download a GUI interface, if you'd prefer to work in a windowized environment, rather than the command line. If you prefer that, take a look at [Git's guide to GUI apps](https://git-scm.com/downloads/guis). 72 | -------------------------------------------------------------------------------- /StyleGuides.md: -------------------------------------------------------------------------------- 1 | Style Guides 2 | 3 | 4 | This page is about creating a style guide. It covers things to think about when creating a style guide and sources for style guides. It is not, however, a style guide. It is not prescriptive. (It also does not discuss tools.) 5 | 6 | There is one basic premise: **A style guide is a good thing to have.** 7 | 8 | 9 | ## Before you begin: 10 | 11 | 12 | Before you start writing that style guide, keep these ideas in mind: 13 | 14 | * Get buy-in from management, other writers, engineers, PMs - anyone who will have to use the style guide - that it's time to make and start using one. 15 | * Make sure your style guide is aligned with any corporate branding. 16 | * You might not have to create your own style guide from scratch. Check around at work: 17 | 18 | * Your company, if it's big, might have other technical documentation teams that already have one. You might even end up being the "hero" that finds a few of them and starts a global style guide project. (That happened to me once.) 19 | * Your company might have a corporate communications guide, a marketing style guide, or other internal guides that you can build upon. 20 | * Someone else at your company might have started a style guide that languished but could be a place to start. 21 | 22 | * Determine who your contributors will be. Good help and input can and should come from more than just official technical writers. Support Engineers, Product Engineering, Marketing and Sales are all places to look for collaborators. You will also likely need sign-off from your Legal department for some stuff. 23 | * Decide where your style guide will live, how people can contribute to it, and stuff like that. In my experience putting it somewhere like a wiki is a good compromise between having it be easily viewed by anyone who wants to see it and worked on by anyone who wants to work on it. 24 | 25 | 26 | ## Resources: 27 | 28 | To help you out if you do have to create a style guide from scratch: 29 | 30 | * Standard style guides that are useful places to start: 31 | 32 | * Chicago Manual of Style (http://www.chicagomanualofstyle.org/home.html) 33 | * Microsoft Writing Style Guide (https://docs.microsoft.com/en-us/style-guide/welcome/) - supersedes the old Microsoft Manual of Style 34 | * Handbook of Technical Writing (http://www.powells.com/book/-9781250004413) 35 | * Wired Style Guide (if you can find an old copy) 36 | 37 | * Publicly-available, comprehensive company style guides: 38 | 39 | * Apple (https://help.apple.com/applestyleguide/) 40 | * Tech Prose (http://www.techprose.com/assets/techwriting_guidelines.pdf) 41 | * Rackspace (https://rackerlabs.github.io/docs-rackspace/style-guide/index.html) 42 | * Google Developer Documentation (https://developers.google.com/style/) 43 | 44 | * Ask in the Write the Docs Slack. I feel confident at least a few of us have style guides we're happy and able to share with you. 45 | 46 | 47 | And now, the meat of it: 48 | 49 | 50 | In the real world, we generally don't have time to make our style guide as detailed as we'd like it to be right off the bat. So, first tackle the more important stuff, then after that go for it all! 51 | 52 | Always remember accessibility. A very easy example is that "above" and "below" mean nothing if users are using a screen reader because of a visual impairment. Use "previous" and "following". Basically, if it takes that little effort to make something more accessible, there's no good excuse not to do it. 53 | 54 | Also remember gender neutrality. It's one thing to say "the user" and "he/she", but that doesn't cover it all. First of all, we now generally recognize that gender isn't binary. Also, it's awkward. You can avoid the whole thing by writing in the plural: "Users...". Or, use the second person and write directly to your users. 55 | 56 | ## First pass 57 | 58 | 59 | Elements you probably want to make decisions on as early in the process as possible: 60 | 61 | * Company product names, including trademark attribution, capitalization, and any allowable short forms 62 | * Legalese page (your Legal department might already have this for you): 63 | 64 | * Disclaimers 65 | * Proprietary and/or confidentiality statements 66 | * Copyrights 67 | * EULA 68 | * Anything else your company requires 69 | 70 | * Who is your audience? 71 | * Doc set architecture 72 | * Doc directory structure 73 | * Document naming convention 74 | 75 | Style Elements 76 | 77 | * Verb tense 78 | * Active v. passive voice 79 | * Tone: conversational? didactic? something in between? 80 | * Are contractions acceptable? 81 | * Use of courtesies 82 | * Title v. sentence case for headings, captions, titles, table column headings 83 | * Graphics/screenshot guidelines: output format, callout style, naming convention 84 | * Links: do they use something like "click here" or show the URL? 85 | * SEO strategy 86 | * Obviously there are lots more. Please add to this list! 87 | -------------------------------------------------------------------------------- /TestingDocs.md: -------------------------------------------------------------------------------- 1 | # Getting docs tested 2 | 3 | 4 | 5 | Docs need QA testing, just like software. If the documentation doesn't work, then customers might assume the product doesn't work. Suppose a customer reads that a line of sample code in your docs will make the software do something magical; then when that bit of code gets pasted in the terminal -- nothing happens, or worse, the customer gets an error. Customers will quickly conclude that the product does not work or is too difficult to use, when the problem might be an outdated or incorrect code sample. 6 | 7 | Accurate documentation matters because it affects the customer's perception of a product's reliability and ease of use. A documentation bug can be as damaging to the company's reputation as a software bug. 8 | 9 | ## What You'll Find When You Test 10 | 11 | 12 | * Inaccurate instructions that were based on internal documentation or your notes from interviewing engineers (Engineers are smart, but that doesn't mean that everything they tell you is correct.) 13 | * Missing steps that are necessary but not documented, because they seemed implicit when the instructions were written. Any documented procedure for using a product is useless if one key step or multiple steps are missing. 14 | * Software bugs. Find out how to file a bug in your development environment. 15 | * Outdated information that was true several versions ago, but wasn't updated at some point when the product changed. 16 | 17 | ## How to Test 18 | 19 | 20 | The best method for testing documentation is to follow the procedural part of the docs, step by step, including installation and using all the features of the product. This is more robust and reliable than a doc review (in which engineers read your docs and sign off), but it takes a lot more time. The most practical approach is to ask engineers to review everything, and test as much as you reasonably can. 21 | 22 | When testing, consider these guidelines: 23 | 24 | * Be very careful to assume that the product's eventual user does not know even the most basic things that you already know about the product. If the doc does not say, "Do X", then don't do it during the testing. 25 | * Plan your testing ahead of time. Unless your documentation is short, a systematic approach will be necessary to test the entire contents. 26 | * Document every error or bug that you find, because you'll have data to show your managers that testing the docs is a valuable use of your time, and that you are making big improvements. 27 | 28 | Decide how formal the documentation of your testing should be. One approach is to check off each line in the documentation on a printed page as its accuracy is verified. A more systematic approach is to create a table or spreadsheet, with each line of documentation inserted into a cell of the first column. (The approach you choose might have to depend on who does the testing, and how much time they want to spend.) 29 | 30 | The spreadsheet approach gives the following benefits: 31 | 32 | * You can add columns to enter the pass/fail status of the passage of text, the platform it was tested on, who did the test, what the pass/fail criteria were, links to any JIRA tickets that resulted, and any additional comments. 33 | * You can use formulas in a table to produce statistics about your testing, like what percentage of the information was correct. 34 | * You have proof that you tested individual lines of text in the docs, and when you tested them. 35 | 36 | ## Who should test the docs? 37 | 38 | * Writers should test the entire doc set to verify that everything in it is accurate -- even though this is not comprehensive testing. The writer, developers and quality assurance people might know the product well enough that they automatically fill in missing steps or gloss over areas that aren't explained well enough for a customer. For that reason, writers and engineers cannot be the only testers. 39 | * A new employee who needs to learn the company's products is an ideal tester, if you approach them at the right time. Sales engineers are strongly motivated to understand the product and to give you feedback when it doesn't work. And they might consider it a favor if you make sure they get the latest copy of the software and all the documentation. Newly hired support engineers might also be good prospects, if your company expects them to know the product deeply. 40 | * Any intelligent person who is outside of the engineering part of the company and willing to test the docs is a good potential tester. 41 | 42 | ## Automated Testing with Linters 43 | 44 | 45 | You can use linters to automatically test for things like prose problems, spelling errors, style issues, malformed html, and broken links. 46 | 47 | You can run these tests yourself, or you can run these tests as part of a continuous integration (CI) workflow. 48 | 49 | Here are some examples: 50 | 51 | * `Vale `_ is a prose linter that allows you to check against pre-defined rules and create your own rules (for everything from terminology to the passive voice)! 52 | * `Alex `_ is a linter for catching inconsiderate language. 53 | * `HTML Proofer `_ can check your rendered HTML for code issues and broken links. 54 | 55 | ... and many more! 56 | -------------------------------------------------------------------------------- /AuthoringTools.md: -------------------------------------------------------------------------------- 1 | 2 | # Authoring tools - selecting 3 | 4 | 5 | 6 | When choosing an authoring tool, think about your audience and your content creators. For the purposes of this discussion, let's think first about the differences in writing for end users versus software developers. 7 | 8 | 9 | 10 | ## Choosing an End User Content Tool 11 | 12 | 13 | Ask yourself these questions about your audience before choosing a tool for delivering end-user content: 14 | * Is my audience very visually oriented, or otherwise uncomfortable with reading long passages of text? If so, you may need to consider using graphics and videos in your documentation. 15 | * Does the user content need to interact with the application? For example, would it help if a user could click a button in the documentation and have it open up the window the documentation is describing? 16 | * Will users read the documentation offline, or in situations where they may not have access to a computer? 17 | * Will users be reading this documentation on a mobile device? If so, which platform? 18 | 19 | You also need to understand your content creators: 20 | * Are they comfortable with version control systems like Git? 21 | * Are they comfortable working in a markup language, or do they require a WYSIWYG (What You See Is What You Get, describes a graphical interface much like MS Word) interface for editing? 22 | * Are they professional technical writers, software developers, or a variety of people with different job descriptions? 23 | * Do they have the skills and tools to create video or graphical content? 24 | * Do they understand how to design and write clear, concise, and helpful content? 25 | * Is creating content a rewarding experience for them, or a chore? 26 | 27 | Some of the same tools recommended for Software Developer documentation may work for you if your content creator community has a high level of familiarity with technology and is comfortable working in a markup language. 28 | 29 | ### Non-Technical-Writer Content Tools 30 | 31 | 32 | If your content creator community is made up of non-technical writers, and is more comfortable in a word-processing (WYSIWYG) type of editing environment, you may find these tools useful: 33 | * Atlassian Confluence (a wiki with a word-processor-style editing interface) 34 | * Google Docs (an online word-processor with simple editing tools and commenting features) 35 | 36 | ### Technical Writer Content Tools 37 | 38 | 39 | If your content creators are mainly technical writers, and need the power of more complex authoring tools, there are many options. A few of these are: 40 | * Madcap Flare and other online help authoring tools (provides level of application integration) 41 | * Oxygen for DITA (single-source authoring in XML, publish to many formats) 42 | * FrameMaker (traditional word processor, can publish to HTML, DITA, or PDF, among other formats) 43 | * MS Word (publish to PDF) 44 | * Atlassian Confluence (wiki can be made to look like a traditional web site, many plugins to support authoring needs) 45 | * MediaWiki (great user community to support customization, wiki-style authoring) 46 | 47 | ### Visual Documentation Tools 48 | 49 | 50 | If your community requires visual documentation, look into video and graphics authoring tools: 51 | * Flowcharts (OmniGraffle, Gliffy, Visio) 52 | * Screen capture (SnagIt, platform-specific tools) 53 | * Video capture (QuickTime, SnagIt, platform-specific tools) 54 | 55 | No matter who your content creators are, it will help to have a way to create templates for specific kinds of documentation so that they have a starting place that conforms to your style guide. 56 | 57 | 58 | ## Choosing a Software Developer Content Tool 59 | 60 | 61 | If your content creators are software developers, they may be more likely to keep the documentation up-to-date if the documentation lives with the code. This usually involves writing in a markup language, such as: 62 | * Markdown 63 | * reStructuredText 64 | * doxygen 65 | 66 | How you deliver documentation written in a markup language depends on your audience. Ask yourself a few questions: 67 | * Is my audience internal or external to the company? This will affect whether you have to get external web site hosting for your generated static web pages. 68 | * Is my audience going to be working with code from GitHub? This may bias you toward using a solution that involves publishing from GitHub, such as ReadTheDocs. 69 | * Does my documentation need to be interactive -- for example, do I want to let users try out a JavaScript API in the browser, or see the real-time effects of code samples? 70 | 71 | ### Publishing Developer Documentation 72 | 73 | 74 | Markup languages require some mechanism for publishing the content to a web site -- otherwise, the content can only be read by those who visit the source code repository. Some popular opensource publishing tools include: 75 | * Sphinx (builds static web pages from Markdown or reStructuredText) 76 | * doxygen (builds static web pages doxygen markup or Markdown markup in the code) 77 | * MkDocs (builds static web pages from Markdown) 78 | * ReadTheDocs (builds static web pages from Markdown or reStructuredText from GitHub repos) 79 | 80 | ### API Documentation Generators 81 | 82 | 83 | API documentation has very specific needs that may require more interactivity. If you're documenting an API, ask yourself: 84 | * Is this a JavaScript (REST) API? 85 | * How will you support docs for each version of the API? 86 | * How will you create API usage examples and keep them up-to-date? 87 | * How much interactivity does the audience require? Should they be able to "try out" the API in the documentation? 88 | * Will the author manually create the documentation, or do you need to generate as much as possible from the code structure itself? 89 | 90 | Several tools exist to help with creating automatic API documentation for a variety of languages. This is only a few: 91 | * pydoctor (Python) 92 | * doxygen (C++, C, and several other languages) 93 | * javadoc (Java) 94 | * Godoc (Go) 95 | * Swagger/swagger-codegen and RAML (REST/Javascript -- interactive API exploration) 96 | 97 | Note that auto-generation tools are not that useful if the developers do not write descriptions for the API in the code. Creating templates for common IDE tools or editors (like emacs) can help encourage the creation of content for each API function. 98 | 99 | API documentation also does not replace the need for examples and tutorials. 100 | 101 | 102 | -------------------------------------------------------------------------------- /DocTeamProcedures.md: -------------------------------------------------------------------------------- 1 | 2 | # Doc team procedures 3 | 4 | 5 | As a lone writer, there is no one covering for you when you are out at the dentist or on a vacation. The developers, support engineers, and other product team members should be enabled to develop information when you are there and when you aren't. To keep these contributors going, you should have a set of guidelines that they use to produce, review, and submit that source content. Does this mean there is no need to define the processes that you use to take that raw information and turn it into the published documentation? Even though you know what you do and how you do it, there is still a need to document your writing and publishing processes -- that's right, document the documentation. 6 | 7 | Why, you ask, do I need to document my processes when no one is going to do them while I am away? Well, there is always the "hit by a bus" scenario and another writer would need to quickly step in. In addition to the possibility of that statistically unlikely event, when you think through your process and write it out, you find its flaws and you improve it. And another plus, if you are a startup that will be seeking additional funding or a possible purchase in the future, having all of this together already will earn you more brownie points than you can imagine. 8 | 9 | But first things first -- put the process and procedures in place so that the contributors (or SMEs, if you prefer) can start providing you with the source content that you absolutely need and then define and refine you own process and procedures for producing and publishing the documentation. 10 | 11 | ## Process for contributors: 12 | 13 | 14 | Whether you are in the office, working remotely, or out on vacation, you should have some procedures and guidelines in place for the people who create and review the source material for the documentation. This includes the format for the information, including text and graphics, as well as how to submit or post their contributions. If collaboration is part of the process, this process documentation should include how each contributor makes edits or comments to an existing document or file and how the workflow is managed (GitHub issues, Jira issues, or whatever you use). Consider what questions the contributors are likely to ask. 15 | 16 | * How are new documentation needs tracked, assigned, and managed? -- Make sure to address how issues/tickets are created and how to define the criteria for new or updated content. 17 | * How is content created? -- Make sure to provide clear procedures for how and where contributors can create new content so that it is ready for the review process. 18 | * How are documents reviewed? -- Make sure to look through your review process, and if any part of that process involves you or any of your tools, you might want to evaluate how those tasks can be done by someone else. Even if your review documents are a bunch of Word files sitting in a shared directory, you can still document where it is and what to do with it. 19 | 20 | The most important thing is to make sure that all of the likely contributors know where to find this information and that it's easy for them to understand. As a lone writer, your time is precious and you don't want to spend large amounts of it explaining these procedures and guidelines over and over again. 21 | 22 | As your contributors use this guide to follow the outlined processes, you can figure out what works and what doesn't. Tweak and update this information as needed. When a potential contributor comes onboard, what they need to know is readily available and you won't be running yet another tutorial about contributing information or reviewing content. 23 | 24 | ## Process for writers: 25 | 26 | 27 | As the lone writer, this is basically just you. But that might not always be the case. If you are at a startup or any other organization that has plans for growth, the day will hopefully come when there is another writer. And maybe later another. And so on. So whatever process and procedures that you put into place, you need to make sure that you address scalability. If you are currently stuck with something that clearly isn't scalable, such as writing a Word document and generating a PDF, make a plan for how to move away from that single-author paradigm. So in this sense, the writing process and procedure documentation will be an evolving artifact and would ideally include plans for how the process and procedures will move forward in that evolution. This will also be an ideal reference when the time comes to submit requests to management for new tools or additional writers. 28 | 29 | In determining how your process will evolve, make sure that you consider the product roadmap. Develop your plans according to how you will need to accommodate the product itself. Is the product going to move to a cloud-hosted, SaaS model? If so, you had better start planning how you will move to a process that can produce hosted documentation that can be easily updated along with the product release cadence. Is the product going to include online help or links to documentation? If so, you should start figuring out how to manage these elements to fit into the UI development process. 30 | 31 | If you’re far enough along in the process at your company and you’re regularly generating draft documents, it would be a great place to start by documenting the tools and processes you currently use to generate your documentation and where the source files and the generated documentation can be found. Next, you can start with some fairly basic style guidelines that include style decisions you have made and any external references that are to be used, such as the *Chicago Manual of Style*. And lastly, add any standards that you have established that are specific to your documentation set, such as how you reference product features or elements or what must be included on each topic or page of published documentation. 32 | 33 | This does not need to be an overwhelming project that takes you away from your writing duties for a long period of time. Carve out an hour or two a week to make some progress. It won't be long before you have something that is far more comprehensive than you even imagined it would be, and it will be a great source when you are ready to add another writer and you have to produce a job description. 34 | 35 | ## A designated writer proxy: 36 | 37 | When you do need to make sure that the assembly line keeps moving along while you are out on vacation, figure out who might act as your proxy in terms of catching all of the documentation issues in the morning meeting and capturing new items in Jira or whatever tracking method you use. This might be the product owner, a developer, or a QA engineer that has been a constructive and thorough reviewer of documentation in the past. 38 | 39 | The designated proxy will need to know what defines an issue or piece of content that needs to be documented, as well as the process you use for creating new tickets/issues. If you include this information in the contributor and/or writer guides, they can use this as a reference and really hold down the fort while you are away, and you don’t have a pile of emails that you need to input into Jira when you return. 40 | 41 | While you’re away, developers will continue to produce new features and new design documents that will be incorporated into the overall documentation that you produce. The proxy can help ensure that these items are not forgotten while you are away, and the Contributor Guide that you produce will serve as a valuable resource to keep things on track. 42 | --------------------------------------------------------------------------------