I’ve worked at a few startups, 1 or 2 that grew large (from <50 people when I arrived to tens of thousands of staff around the world). If your sails do catch the wind and you have to scale up, then documentation is invaluable (that and automation). Documentation needs an owner though, because it generally has a half-life and decays over time. This kind of ownership has to be enforced.
The Surprising Power of Documentation
51–60 of 153 posts
Re: The Surprising Power of Documentation
#52This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…
I'm the CTO of Mintlify - we help other startups create their developer-facing documentation. We've been working in the documentation space for a little over a year now and I spend a lot of time thinking about documentation. I completely agree here. Documentation is such a hard problem to "solve" if you're a fast-moving startup. You need a mixture of creating a documentation-first culture and acknowledging that docum…
I'm trying your extension out and it looks promising.
A tiny bit of feedback: the shortcut key is defined in settings, not keybindings which seems wrong? Also, the default is to override cmd+. which is an important shortcut already..
Re: The Surprising Power of Documentation
#53One thing said in another article that has really stuck with me on documentation is that it helps you scale yourself. You can only have so many meetings and so many discussions everyday. Maybe manage 5-10 people tops.
With good documentation, it can be used to scale yourself beyond what you can personally do everyday, and it works really well when you can convince people to search for answers before asking
Re: The Surprising Power of Documentation
#54It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that). The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things…
Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".
Re: The Surprising Power of Documentation
#55Earlier quoted context omitted.
I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_h…
I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…
It's true that there can be gotcha's in code which should be documented, but I don't think forcing a template on people is the solution. In fact, I wouldn't expect people to be better at documenting them with that in place.
Re: The Surprising Power of Documentation
#56Problem with documentation is that there are a lot of uses for documentation. It can be a reference, it can describe the architecture, it can do many things. Probably a good idea to figure out what the intent is first to find a good form. Some of my stuff is pretty sprawling, I've started integrating the documentation with the code and basically use readme.md's littered in the code as sign-posts to let you navigate i…
Hesitant though I am to recommend an approach to structuring documentation which needs its own documentation, the structure followed by the Django docs is straightforward to apply: https://mattsegal.dev/how-to-read-django-docs.html
Re: The Surprising Power of Documentation
#57"Documentation" as a term is almost catastrophically overloaded, and just "documenting" things is only half the battle. I'll take semi-documented systems if the information architecture is good; perfectly documented components in an unnavigable mess is no good if I can't find the document that would help me.
Re: The Surprising Power of Documentation
#58[flagged]
Re: The Surprising Power of Documentation
#59Some nice quotes in this article that center on the idea of finding a better tradeoff between on the one hand, documentation as a vehicle for knowledge sharing, and on the other hand, meetings as a vehicle for knowledge sharing (when they should be about decision making).
"You can think of Documentation as essentially the backbone of effective knowledge sharing."
"In the words of Bukowski, 'Don't do it unless it comes out of your soul like a rocket', apply the same principle to meetings."
"The constant need to have meetings is a symptom of a deeper problem — a lack of clear, accessible, and reliable documentation."
"Encourage your team to document their decision-making process to clarify assumptions, reasoning, and expected outcomes. Make it a standard practice to discuss these documented decisions in your meetings, promoting a culture of open feedback and collaborative decision-making."
Re: The Surprising Power of Documentation
#60All this assumes one important thing: That people will read what you put in front of them.
I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate.
People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket that says exactly what is happening and lists the ten things I've already tried to resolve it. 100% of the time, the first reply is to ask if I've tried doing any of the first three things I said I already tried.
It's that kind of thing that makes me think documentation is hopeless. Nobody's going to read it anyway.