9 ms·
Writing Documentation When You Aren't a Technical Writer
- Multicomp 8y agoWhen I'm writing documents for whoever touches a system behind me, I write wiki articles on what the system is/does, logical data flow diagrams, and a deep dive into whatever it was that I just touched. From there, I make a condensed narrated PowerPoint with pretty charts and UI element screesnhots. If I have bonus time, I might even make a basic Chamilo course to cover the application and immediate dependencies and ecosystem. This all sounds great to write, but I wonder how much of the work actually gets used. The devs that wrote the program often don't bother with documentation (fail fast and fail forward!) so I have at least a small sense that wiki searches etc will surface my material, but I wish there was a better way to track who found what useful or not without them walking up to me and personally commenting on it. Suggestions to up my documentation after the fact game are welcome.
- sicher 8y agoI have worked extensively on the documentation for the Defold game engine (see https://www.defold.com/learn/ https://www.defold.com/learn/). Here's a few things we've done: We use Google tracking on the site. That helps a bit. We have search available on the site and we get the most useful information from how people use the search function. We get clues as to what users are looking for, what terminology they use and I use that to make sure common searches turn out good information. I added a "Have a suggestion?" button at the bottom of each page. You have to be logged in to see it (because of bots) but it allows you to mark text directly on the page and then report errors and suggestions. We get a lot of feedback through it, much, much, much more than before when we relied on users sending their feedback or stopping by to talk.
- andygcook 8y agoGood instincts on the suggestions feature idea. My startup builds internal documentation software. We built that exact feature and our customers really like it. The problem with most documentation is that it goes out of date. Wrong docs are often more detrimental than no document at all. Allowing readers to flag information that might be wrong, or even suggest an update to merge, helps to harness a team’s collective knowledge to keep documents updated.
- reacweb 8y agoAs a programmer, when I write documentation I try to make this work profitable for me. First, I open the specifications I had and I try to describe how it was implemented. Often, this means I have to give a look to my code or tests and this makes me identify a bug or a missing test. I try to be concise and to avoid repetitions because big documentations are more expensive to maintain. At the end, I try to imagine the future me who will have completely forgotten this project and will be asked questions by users who will start using it. When I finish a project, I free my mind of all the details.
- rodionos 8y agoWe adopted a set of formal guidelines [0] for our database docs, based on Google Developer Guide [1], and automated the checks as much as possible with linters [2]. The checks cover spelling, markdown formatting, broken links, and grammar/style. For instance, we specifically reject hostnames, domain names, IP addresses, person names, phone numbers unless it's on our Example List[3], which itself is largely based on RFCs. [0]: https://axibase.com/use-cases/tutorials/workshop/technical-writing.html#grammar https://axibase.com/use-cases/tutorials/workshop/technical-w... [1]: https://developers.google.com/style/ https://developers.google.com/style/ [2]: https://github.com/axibase/docs-util https://github.com/axibase/docs-util [3]: https://axibase.com/use-cases/tutorials/workshop/technical-writing.html#example-names https://axibase.com/use-cases/tutorials/workshop/technical-w...
- yread 8y agoI like your list of blacklisted words!
- lewiscollard 8y agoI like the idea of CI to enforce it :) I'm tempted; I wonder what the GP uses for that.
- rodionos 8y agoWe use Travis CI for checks as well as github and travis webhooks to deliver warnings to specific committers who need to fix the errors in a particular PR. Scheduled Travis CI checks send alerts to the general channel if the master branch starts failing.
- avian 8y agoI wonder how well this works. Word blacklists tend to be very crude tools. For example, how often must people actively spend effort working around all the blocked past tense forms? How do you express that something used to work differently in a previous version under these restrictions?
- b0rsuk 8y agoWhere I work, technical writers earn 0.92 of a developer's wage, while a team leader earns 1.4 of a developer's wage. These are calculated from actual contract with our client. While I'm pretty good with some documentation tools like docutils and graphviz, it makes me wish not to pursue documentation skills too much.
- dickeytk 8y agoThat's a poor reason. Learning how to write effective technical documentation is a great skill for anyone in our field. Even a team lead should be able to edit/review technical documentation.
- _jal 8y agoDishwashers earn a tiny fraction of a developer's wage, I am quite proficient at washing dishes, and yet I have no fear of trapping myself in a career of dishwashing. I can think of very few non-contrived workplace situations in which being bad at something is an advantage.
- k__ 8y agoIt helped me to blog about technical things to become better at technical writing.
- TheAceOfHearts 8y agoSome thoughts on documentation: 1. Don't do things in your examples which you consider anti-patterns. A few years back I remember some Angular 1.x docs which showcased certain examples which the authors considered anti-patterns. Why are you surprised that users are doing things the wrong way if you're the one that taught them? If you must provide an anti-pattern examples for the sake of brevity at least note it near the code sample and explain what the correct usage should be. 2. Give examples of what certain features or options could be used for. I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose. If you added the option it means you must've thought of some use-case for it, right? It's pretty useful when you're not familiarized with a domain and you want to build up the knowledge of its use-cases in case you have to deal with related problems later on. 3. If something is deprecated or its usage is discouraged be sure to point users to the proper solution. I've encountered warning blocks on MDN which suggest using a certain API, but when you click through it turns out that it's deprecated and they tell you that you shouldn't use it. Contradictory information is incredibly frustrating.
- blattimwind 8y ago> Some thoughts on documentation: Complete, syntactically correct sentences that make sense. Paragraphs / sections that have a start and an ending. Clear, concise and consistent language (part of the "7 Cs of communication that actually works"). Documentation is not a poem-writing contest. Do not substitute pseudo-synonyms (e.g. table, relation, schema), that's inconsistent and confusing. Explain concepts and define key terms. A glossary tends to be immensely helpful, especially if it links back to detailled explanations of home-grown terms. And the usual basics, e.g. think about the intended audience (what can you expect them to know, what do they want, then give them that).
- Sean1708 8y ago> I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose. I won't name and shame the author because it's just a little personal project, but my favourite example of this is the following bit of documentation: get :: JSON → JSON → JSON Get the value at k from the object While I can use common sense to guess at the order, I have absolutely no idea how you're supposed to index JSON with JSON.
- Timpy 8y ago>Users skip over things that look like ads, so be careful how you display images Several paragraphs earlier the author writes "Do you know that feeling when The Onion is eerily right?" and I had no idea what they were talking about until I realized they were referring to the picture right next to it. I thought it was an ad.
- Kurtz79 8y agoSame here. Relevant XKCD: https://xkcd.com/570/ https://xkcd.com/570/
- LarryL 8y agoGreat articles (there is a part 2 here: https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-two-59997587cc2a?source=collection_home---1------0---------------- https://blog.stoplight.io/writing-documentation-when-you-are... ) The article is about API documentation, but the points apply to every documentation. I think however that a few things are missing in the articles: 1- an OVERVIEW/INTENT page/paragraph. This is THE thing that is missing in almost every -if not all- documentation I've ever read. An example that I always use to illustrate the point: the "File" API. In EVERY documentation I've ever seen, the usage of each function/method is detailled, but NOT why some function must be used before others (opening a file is NOT an obvious concept); the concepts (what is a file?), the workflow are NEVER explained. And Files are basic stuff, what about GUIs? Ever used a big GUI toolset? It's miserable! They never include the high level stuff, you have to dig a lot and if you are lucky, maybe you'll find a blog womewhere that gives a few insights in the mind of the creators. IF you are lucky. So you end up using the wrong type of widget or function (because they look alike) until you crash & burn and realize that it was the wrong choice for your purpose, because NOTHING is explained, you have to discover everything at your cost. 2- graphics/workflow charts This is related to my first point. When I write documentation I include -at least- one high level graphic that shows how the various parts of the system interact, sometimes a flowchart or a Finite-state diagram (when a FSM is used, obviously). ----- When I give a module to my coworkers (be they testers or users of my API), I give them that additional documentation which makes it MUCH easier to understand and test/use. What I find stunning is that I'm always the ONLY ONE to do so! At most my coworkers will write _some_ documentation to explain a few difficult points, but it will mostly be comments, not documentation for an user of their API/module. And if you point it out, the reaction will range from "I've no interest in that" to "it's not necessary, the code talks for itself"... To them, the -automatically generated- JavaDoc comments are "enough", which is total B.S. The most infuriating is that all this -undocumented- code is always the result of a HUGE amount of work and dedication. But it is invariably cruely hobbled by that missing step: helping the users use it properly. I see it everyday in Free/Open source tools, and I've seen it in every project in the companies I've worked with (except mine of course)... So you spend lots of time trying to understand how the stupid thing is supposed to work instead of doing your real work. There is a LONG way before the importance of documentation (and comments) is accepted as what it is: VITAL. Unfortunately, as for testing and security, management not only don't encourage the practice, but they often discourage it (poo-pooing -or worse- such concerns).
- uweschmitt 8y agoThe referenced report from Nielsen-Norman is from 2006 and outdated. They published corrections at https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/ https://www.nngroup.com/articles/f-shaped-pattern-reading-we...
- tbarn 8y agoAuthor here. I did mention part of this in the blog post: > The study also found some alternative scanning patterns such as layer-cake pattern, spotted pattern, marking pattern, bypassing pattern, and commitment pattern. > It’s important to note that F-pattern is [negative for users](https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/ https://www.nngroup.com/articles/f-shaped-pattern-reading-we...), but good content design can help prevent F-shape scanning.
- rhizome 8y agoIt looks like you have a whole section about it, adding a "never mind" at the end? Am I reading it incorrectly?
- BelgradePhantom 8y agoLike it!
- andrepd 8y ago>Medium To make Medium work, we log user data and share it with processors. To use Medium, you must agree to our Privacy Policy, including cookie policy. Is there another place to read this?
- trishmapow2 8y agohttps://outline.com/UV57G9 https://outline.com/UV57G9 Protip just prepend outline.com/ to any web address and it will give you a nice stripped down version.
- akudha 8y agoThere seems to be lots of good quality content on Medium, but it is quite annoying to use - like a quarter or so of the page is taken up by the navigation bar and the stupid "get updates" bar at the bottom, (13 inch monitor) :(
- austincheney 8y agoI found that when I was manually updating documentation I could never keep it perfectly in sync with the code. Now in my open source app the documentation is fully automated and generated as a part of the build process. The interactive documentation covers the app's use in a browser, command line, and static documentation is various formats.
- tbarn 8y agoThis is very closely related to the idea of a single source of truth that good docs built with OpenAPI Specification use, which is what the company I work for is built on top of (https://stoplight.io/ https://stoplight.io/). There will almost always be docs you need to update manually though.
- devxpy 8y agoIs it just me or the community is just filled with packages that have a single page, or nearly single page doc. Please don't do this. Documentation isn't an rfc. It's meant to be a _content first_ WEBSITE! - plain html with little styling. Use the standard documentation themes if possible ( like read the docs ) - lots of cross references. Each class/func should be referenced back to it's API. (Sphinx is really good for this)
- habosa 8y agoIve been doing developer relations at Google for 4+ yrs now and the points about code snippets in this article are great. Let me add another one though. Find a way to pull your code snippets from real code. What I mean is, write the code snippets somewhere that you can use a your normal coding tools and make sure they all compile. Publish this repository of snippets on GitHub or similar. In your doc system, have the docs pull the code snippets from the repository at page generation time. This repository should have basic CI to make sure the code and dependencies are valid. If you write snippets directly in markdown or html, they will eventually be wrong. Even if they start correct, it will be a real pain to update them for v2 of your API. Every team I've ever seen that thought they were the exception to this rule was wrong.
- franciscop 8y agoI did it the other way around; I wrote the tests within the code snippet (https://news.ycombinator.com/item?id=17837016 https://news.ycombinator.com/item?id=17837016). I was going to remove them when rendering, but in the end I thought they might actually be helpful and clarify things, so I left the tests within the snippets. For reference, here is the JS test builder (fairly rough): https://github.com/franciscop/server/blob/master/test/examples.test.js https://github.com/franciscop/server/blob/master/test/exampl...
- chaoticmass 8y agoWhile there are many excellent style guides out there, I personally went with the IBM Style Guide: Conventions for Writers and Editors [0] when I started writing technical manuals and documentation. It is so comprehensive that the book ends up describing itself exactly, as if it were some kind of meta manual. [0]: https://www.amazon.com/IBM-Style-Guide-Conventions-Writers/dp/0132101300/ https://www.amazon.com/IBM-Style-Guide-Conventions-Writers/d...
- mr_tristan 8y agoThis is a good overview on how to structure a particular page, but what about the structure of overall documentation? I've actually found several good articles about writing articles, but little about organizing many of them. I find that most documentation that goes into a wiki, e.g., Confluence, begins and ends life as a plan. It is then surrounded by business process clutter. And then the true gems of reports about performance analysis or other details just get buried. What would this be even called? Taxonomy? I sometimes wonder if I could convince people to call wikis, google docs, etc, a "library" and we should have a librarian go organize everything. Because it's a little sad how much knowledge just gets lost.
- chrishynes 8y agoYep, this! Lots of articles about low level writing, not much on the high level. I've always liked the old school documentation layouts when it used to be printed -- programmers guide, function reference, etc. but sometimes it escapes me how to apply that sort of structure to other domains.
- kaycebasques 8y agoTechnical writers call this "information architecture". Hierarchical organization is tough. E.g. if you're working on a docs site, and you have a multi-level nav, what's the best way to organize that nav? Same problem with organizing the directories in a company's intranet. One idea that is influential within the technical writing community is to "treat every page as page one" [1]. Because of Search, you never know how people will first access your docs. So you always structure every page to handle one topic, and only one topic, thoroughly. And then link profusely to other docs that the user might be interested in. [1] https://everypageispageone.com/the-book/ https://everypageispageone.com/the-book/
- tbarn 8y agoAuthor here. This is a great point! Stay tuned for part 3 or 4 in the series where I cover some of this stuff.
- kaycebasques 8y agoI'm a technical writer. I write the docs for Chrome DevTools and Lighthouse. The tips in this article are mostly fine. Nothing controversial there. It has some good advice, but ironically, the article itself doesn't follow its own advice. > The first two paragraphs must state the most important information. The most crucial skill for creating quality documentation is to know your audience and then write for that particular audience. What knowledge are they bringing into the doc (and therefore you don't need to cover)? What knowledge are you assuming that they know? What if they don't have that knowledge? Hint: They'll probably find your doc confusing and frustrating. What is their likely emotional state going into a doc? E.g. if you're documenting an error code there's a higher chance that they're panicked, so don't waste their time! Given a particular audience, what exactly is "the most critical information"? "Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know. It's a lifelong journey. But the more you focus on this concept, the better all of your communication will get. I could go on for years about all sorts of interesting tips for improving your writing, but it's all a waste of time if you don't have an overarching guiding principle. And that principle is to know and write for your audience.
- misterbowfinger 8y ago> I could go on for years about all sorts of interesting tips for improving your writing Please do! Do you have a blog or something to follow?
- kaycebasques 8y agoI write here and there on my personal site [1]. The intended audience of the few things I’ve written were geared more towards practicing technical writers, but maybe it’s high time to cover the fundamentals. There’s a mailing list at the bottom of the post I’ve linked to, where you can get a ping whenever I publish a new technical writing post. [1] https://kayce.basqu.es/on/metrics https://kayce.basqu.es/on/metrics
- maxhallinan 8y agoI really enjoyed your blog! Please keep writing.
- DrBazza 8y agoTerse and unambiguous. That's it.
- dragonwriter 8y ago“Terse and unambiguous” -> “concise”.
- b0rsuk 8y agoOverall, disregard for documentation in places I worked in puzzles me. I like to say: Documentation is memoization for communication. Training courses and videoconferences are overrated. A guy gets to wear a suit and (usually) point at some slides. I don't see the benefit of being able to ask questions, because people feel intimidated and few questions are asked. And whenever some new employees arrive, you have to redo the whole thing. To be sure, there's plenty of shitty documentation. But I think it's the problem with the writer not making an effort to put himself into reader's shoes. A technical writer should be eager to clarify, and improve documentation. His goal should be to be understood, not high page output.
- franciscop 8y agoI had an "oh f_ck" moment around docs in my OSS project: I made a small mistake. I wrote "@include" instead of "@import" in the homepage of a fairly well-polished project, https://picnicss.com/ https://picnicss.com/. Now, I don't want to imagine how many developers copy/pasted that snippet into their code, saw that it didn't work and blamed their code a hundred times until they ultimately gave up and left the library or SCSS altogether. But it wasn't until a poor soul opened an issue in Github (which made me feel horrible) that I realized how much responsibility people writing the docs have. So I decided I had a to do something for my next project, and I did. Every snippet of code should be tested, see this as an example: https://serverjs.io/documentation/context/#-options https://serverjs.io/documentation/context/#-options const mid = ctx => { expect(ctx.options.port).toBe(3012); }; /* test */ const res = await run({ port: 3012 }, mid, () => 200).get('/'); expect(res.status).toBe(200); In the build process, that snippet will be captured, the test extracted and run. That way, as a one-man dev, I can make sure that my snippets are tested and working automatically. I've gotten busy since then and haven't had the chance to refactor the code or test all the examples as I'd love, but many of those tests are still there, making sure the code examples are working.
- kaycebasques 8y agoThat's cool that you've found a way to test the code that's embedded in your docs. Google has infrastructure for inserting code from a GitHub repo into docs [1] but I haven't heard of anyone extracting the code from the docs and testing it. One thing that you might want to look into is conditionally displaying parts of the code. For example, suppose that for a given doc, you only need to display one line of code. But to get the code runnable, you need to put in some boilerplate. There should be a way to only display the one line of relevant code. // START_EMBED fetch("example.com"); // END_EMBED // Boilerplate infrastructure that the user doesn't need to see. new Test().run(); One advantage of the Google approach is that you write the code once, but can insert code one line at a time into the doc. For example, suppose you start off with the full code sample. const service = new Service(); service.init(); service.doStuff(); service.terminate(); But then you want to discuss the first line: const service = new Service(); Then the second, and so on. The Google markup looks something like this: // START_FULL // START_CONSTRUCTOR const service = new Service(); // END_CONSTRUCTOR // START_INIT service.init(); // END_INIT service.doStuff(); service.terminate(); // END_FULL And then to embed a certain snippet into each doc you just do something like this: {% includecode "https://github.com/.../code.js" snippet="FULL" %} [1] https://news.ycombinator.com/item?id=17835045 https://news.ycombinator.com/item?id=17835045