91–100 of 203 posts
Yes, there is a place where you can hear about those things: The Write The Docs community: https://www.writethedocs.org/ (They also organize conferences every year.) It was really eye-opening when I visited a conference and heard those things the first time, it is highly recommended for everyone! https://www.writethedocs.org/conf/
Earlier quoted context omitted.
When I was super green I argued about this with the principal engineer for quite a while about swagger. Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?
I'm for swagger but only if the router uses it. I keep hearing swagger / contract first. But then they still manually specify `/api/v1/user/login`. Vertx web api contract router. Which takes in a swagger file, and routes based on the `swagger` operation id. Is the closet I've seen. https://vertx.io/docs/vertx-web-api-contract/kotlin I've also written a library to route into ktor in a type safe way. But if you're doin…
less code, standard approach, less bugs.
What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this informatio…
Particularly useful if you know X and wondering if/why to consider Y.
I often look at “alternativeto.net” to find products/services because we often choose things based on similarity and points of difference with things we already know.
Thanks for sharing this guide. It's fitting like a ring to finger as I am in the process of setting up documentation for the features of my app [1] because I realized that as an early-stage startup one of the best ways to teach your users how to use your product is by writing great documentation. I'm finishing the setup of this site within my landing now using Gatsby, on the main domain, so that it can also help to b…
Agreed. As someone making a very technical product, I can see how lack of documentation hinders my sales process -- potential customers want to try out my software, but the lack of documentation makes it difficult for them to overcome their inertia. As you did, I plan to spend the next couple of weeks just writing docs. Just want to lend weight to your comment. :) Thank you for posting the podcast.
Hope you enjoy the podcast, there are some gems there about SEO. Ruben Gamez —the person in the podcast— was also technical and learned his way around SEO.
Mind sharing what your product is?
My experience has been that having names for things makes it easier to think and communicate about them; including in documentation. For example, once I learned the term "tail" I no longer had to say "every element except for the first one". As another example, learning about "complete" versus "partial" functions gave me the vocabulary to better understand and communicate about certain types of errors. Does anyone kn…
I think it is also useful to be aware of the specific terms your team might need and introduce words to those more abstract concepts. This frequently happens with naming specific code patterns or important classes in the code, but can also be for how the team operates in general. A DSL for how your team operates.
Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all.
And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.
Thanks for sharing this guide. It's fitting like a ring to finger as I am in the process of setting up documentation for the features of my app [1] because I realized that as an early-stage startup one of the best ways to teach your users how to use your product is by writing great documentation. I'm finishing the setup of this site within my landing now using Gatsby, on the main domain, so that it can also help to b…
Agreed. As someone making a very technical product, I can see how lack of documentation hinders my sales process -- potential customers want to try out my software, but the lack of documentation makes it difficult for them to overcome their inertia. As you did, I plan to spend the next couple of weeks just writing docs. Just want to lend weight to your comment. :) Thank you for posting the podcast.
My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated. Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the…
When I was super green I argued about this with the principal engineer for quite a while about swagger. Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?
If I'm a consumer of some third-party API, there's no practical difference between intended behavior, accidental mutation and a bug which the supplier won't fix any time soon - all of these things are equally part of the contract of how The Thing v1.2.3 works, and that's what I want described in the documentation. Any part of the documentation that says what The Thing should do (but doesn't actually do) is worse than useless, it's actively misleading; it describes some wishful thinking with no connection to reality.
If the contract documentation describes an interface between two parts of the system that I control, and I have the ability to fix discrepancies between contract and code by altering the code, then sure, that's a different situation; but if I don't have the ability to make these changes because it's an API to code made, maintained and controlled by someone else, then accurately describing current reality is the most important thing.
Earlier quoted context omitted.
With Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!
I'm sure you know because you're Steve Klabnik, but for other readers: you can enforce documentation for public items in a crate by adding `#![deny(missing_docs)]` to the `lib.rs` file. Then it just takes some self-control and gold code reviews to make sure you're writing good documentation rather than just short stubs to silence the error.