5 ms·

To your point, it would be refreshing - and appropriate - if more projects baked "documentation-first" into their purpose. For all intents and purposes it's "ma

• Waterluvian 4y ago
  Docs aren’t the fun part of dev.
  • agumonkey 4y ago
    Unless you make it programmable
  • beebeepka 4y ago
    They are more fun to me than writing tests
• whynotminot 4y ago
  It’s not fun to write documentation, and for documentation to be good, it has to be persistently updated. It takes a lot discipline to do things right.
• gervwyk 4y ago
  Because being a small project with limited resources requires devs be as resource efficient as possible. Docs, demos, tuts are all super important but it creates an additional maintenance overhead - if they are not maintained up to date, they become worthless. So for the early stages of a project it makes sense to keep the overhead low and work with a small group of focussed early adopters. As projects grow, mature and become more stable, more investment into learning material becomes important. Doing it too early burns valuable resources.
  • chiefalchemist 4y ago
    > As projects grow... I'd argue if should replace as. The point being docs are all but essential for growth (and added participation). To neglect them is self-defeating. Put another way: Docs are an investment. They have a known return. Again, we've seen this. We know this. Yet again and again there's case after case of docs denial.
  • simonw 4y ago
    I've learned over time that it's much easier to incrementally update existing docs than it is to add them to a large project from scratch - so every single one of my projects, no matter how small, now has documentation from day one. As I add new features I update the docs to reflect the changes, trying to keep those documentation updates in the same commit as the tests and implementation. Since I started doing this the quality of documentation I produce has gone up a ton, because I'm constantly exercising those muscles. It's been a huge win for my coding quality and productivity too - I don't have to remember as much stuff because I can refer back to the docs, and documenting as I go along causes me to make much better design decisions. Worth noting: I'm a native English speaker writing documentation in English, and I've been blogging frequently and writing online for over twenty years so I've accumulated a LOT of writing experience. So what's easy for me may not be easy for other people!
    • gervwyk 4y ago
      This is good advice, thanks. Really want to practice my writing more as well.
    • beebeepka 4y ago
      Good point but writing and maintaining README.md files for your solo projects is nothing like writing proper docs for big projects with multiple contributors and users. That's a full time job, isn't it? Writing non-code is easy and fun to me - I used to do it for a living - but when I am pressed to deliver features, documentation takes a backseat. Also, I've never felt like documenting other people's code
      • 4y ago
• BaculumMeumEst 4y ago
  because time is finite if you spend your time making sure your product works but don’t write thorough documentation, it can become a breakout hit even though some hacker news commenters may complain about a lack of good documentation if you spend your time writing great documentation, the product will suffer and nobody will use it
  • jcpst 4y ago
    > if you spend your time writing great documentation, the product will suffer and nobody will use it This is an unfortunate perspective. And I could say the opposite is true. If you don’t spend time writing great documentation, your product will suffer and nobody will use it. Documentation gets neglected because developers don’t feel like doing it. If you are building a product for developers, documentation is critical.
• jamesgpearce 4y ago
  Agree. But it’s not either/or. I invested easily hundreds of hours in docs before launching TinyBase.org - but I don’t think it made the subsequent community building challenge any easier.
  • chiefalchemist 4y ago
    Yes, fair enough. And I'd like to add Docs !== community Docs === Odds of gaining traction To your point, achieving community is a whole other beast to battle.
• lioeters 4y ago
  I think it's because documentation (and design) requires different skills than writing code. A great programmer is not necessarily a good writer or designer. There are rare gems, people who have a balance of such skills, but most of us struggle to write useful documentation, even the bare minimum necessary for others to get started - or any at all. The code, or the lead dev's brain, is the documentation. A perfect example of this is documentation generated from docblock comments. Some projects only have such docs, and expect users to go from there. It's as if programmers envision their audience as another machine to program. I feel similarly about business/marketing aspects of software projects. Many programmers seem to assume, "If you write it (the program), they will come." Successful software is so much more than just the code, it usually involves a communal effort of various skills, especially human communication, including writing good documentation.
• steveklabnik 4y ago
  Many engineers do not value good docs, even if they say they do. Many people won’t read them at all, no matter the quality, and so it can feel like work wasted. Plus writing docs is a different skill set than writing code that many simply don’t like to do.
• thinkharderdev 4y ago
  The boring (and probably mostly correct) answer is that engineers don't like writing documentation so it is the last thing to get done, if it gets done at all. This is especially true of FOSS projects. You may be motivated to spend your free time hacking on something cool and interesting, but spending your free time writing documentation is another matter.
• deleted 4y ago
  [deleted]
• lewisl9029 4y ago
  These days now that I'm fully in charge of building my own product, I often wonder if we place too much emphasis on centralized documentation sites that users have to deliberately seek out and visit vs in-context documentation snippets that show up as closely as possible to where users might actually need them, deeply integrated into the product and user journeys. Users don't search for documentation for the sake of finding documentation. They search for documentation because they want to know how or if our product can solve a particular problem they have. My hypothesis is that the documentation discoverability problem is really just a symptom of the product discoverability problem, and that centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom, when that effort can be much better spent addressing the root cause by making the product itself more discoverable and deeply integrating useful documentation into it.
  • deleted 4y ago
    [deleted]
  • skybrian 4y ago
    I read the documentation before downloading anything, to find out if the software will work for my problem. I’m not sure that “in context” helps with that?
  • spacephysics 4y ago
    That’s what kaseya is doing with their software, basically having contextual assistance for each feature as an “AI Buddy”, where users can choose to listen/learn or just continue using the product, all integrated as one
  • replygirl 4y ago
    > centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom a searchable docs website is the most important thing for me. having to "discover" an api by stepping through code and comments is a waste of time--only useful when you already know the basics, which requires documentation
  • vlovich123 4y ago
    Centralized documentation is valuable for several pieces: * Easily get an overview of the entire API. I may just be scouting the library, so I want to understand what the API looks like. * Examples as a starting point. How do I use your API? * Makes your product more discoverable / approachable to potential users. Think of your users like a funnel - how are they using the library? What are the common reasons you’re losing potential users? What are the common reasons you’re losing existing users? Users are also different so you have to analyze by cohort. Now can something better be done? Maybe It takes a lot of work and would have to address the above issues and I don’t know if it would necessarily change the need for something centralized.
• lelanthran 4y ago
  > This is one of engineering things that happens year over year. We all understand the value of good docs. Yet it keeps happening. Why? Because doing anything is is irrational? Time is finite, only a rounding error number of projects (especially open-source ones) are going to be successful, with or without docs. Only an irrational developer would think that they are going to hit the 1-in-a-thousand jackpot with their project. Any time spent producing documentation is time not spent on adding features and fixing bugs. Spending time on documentation over and above the bare necessity needed to get out a working product "just in case we win the jackpot" is simply irrational. This is probably why you don't find many projects spending significant startup time on good, clear and comprehensive docs (as opposed to a README and an FAQ and nothing more): the ones that do as you suggest mostly die before even getting users. TLDR; don't treat your startup project as if you already have 5m users who depend on you. The odds are that you are never going to get to that point without a good product, and the better the product, the fewer the docs needed.
• rswail 4y ago
  Because people are "scratching an itch", not creating a product. Most engineers are terrible at writing documentation.
  • chiefalchemist 4y ago
    True. Adding tho' that the original topic isn't a side project. It's a team bringing something to market and looking for participants. And to your point, writing docs *is* something to consider when building the team. As is making sure the culture has a reward system if such behavior is important.
• yen223 4y ago
  Because a poorly-documented product that does something, is much better than a well-documented product that does nothing. Engineers have to decide where to spend their time, and taking time away from feature development when your early-stage product doesn't have many features is not a winning move.
  • replygirl 4y ago
    > a poorly-documented product that does something, is much better than a well-documented product that does nothing not necessarily. with the latter, you know the constraints of a solution and can make an accurate judgment on whether it's worth using
  • wruza 4y ago
    True, but if it’s too early for a good documentation then talking about taking someone’s crown is too early as well.