7 ms·
>No Documentation, No Problem >Who needs documentation when you have the power of intuition? YOLO-Driven Development encourages you to keep your genius solutio
by bobajeff 3y ago
>No Documentation, No Problem
>Who needs documentation when you have the power of intuition? YOLO-Driven Development encourages you to keep your genius solutions locked away in your head. After all, real developers don’t read documentation; they conjure it from thin air.
Apparently this style of development has already become very popular as almost none of the projects that I look at have any documentation at all.
- sleepybrett 3y agosure they do, you have the sourcecode don't you?
- samus 3y agoIf you have an ugly tangled forest of microservices to investigate, even having the code won't save you
- alexjplant 3y agoSome problem domains are inherently complex and the code written for them needs documentation. Some are not but get complicated during the design process and perverted into abominations that wouldn't have required documentation if the design and source were more readable. I'm inclined to say that if you name things obviously and avoid cutesy idioms (AOP/reflection magic, ridiculous object hierarchies, etc) that code can be quite grokkable with little documentation. Of course this falls apart once you start dealing with hundreds of microservices or decades of tech debt but such is life.
- pjerem 3y agoThat’s the theory. In real life, code is written by teams with different levels of skills over multiple periods of time. Expressiveness is a really hard skill that take years to master and that few people have and that you can only learn by yourself.
- _jal 3y ago> Expressiveness is a really hard skill that take years to master It is worse than that. Being good at expressive, self-documenting code correlates with strong communication skills and empathy. So programmers who get good at it tend to increase the risk of managerial borgification.
- adamisom 3y agoDo you mean they’re more likely to become managers and thus no longer write great code, or something else?
- frollo 3y agoIn general, they tend to get snapped up by other corporate roles, either officially (which at least grants them the pay benefits associated with the role) or unofficially. I know a lot of great coders who ended up doing anything but code because they were the technical people with communication skills.
- wheelerof4te 3y agoA waste of good, talented coders. Code written by a junior new hire can't even hold a candle to code written by a true master.
- ibash 3y agoI don’t think it’s that hard to learn actually. This works: 1. Before writing a class or a function write comments about what the code will do (unless it’s absolutely trivial) 2. Check if the comments make sense 3. Write the code That simple practice almost guarantees understandable code.
- scubbo 3y ago> code can be quite grokkable with little documentation Indeed, the code _itself_ can often be understood from reading the code. Documentation is for everything _else_ - explanation of the choices made and motivations when picking a particular design (so that they can be re-evaluated when a redesign is considered), customer-facing onboarding guides, runbooks for how to carry out operational tasks, and so on. That is - https://brooker.co.za/blog/2020/06/23/code.html https://brooker.co.za/blog/2020/06/23/code.html
- munk-a 3y agoThis is quite true and one of the reasons I hate auto-doc comments. If a function tells me that an input is an integer there's no reason to repeat that information in the header above the function unless that information is then being parsed to produce a more readable form of documentation (i.e. as JavaDoc was originally used). Additionally I personally, though I am happy to concede that it may benefit some people, loathe "$documentId The ID of a Document" style comments. If you are adding more information above and beyond what is relevant from code - especially if that information relates to why you chose this approach over a different one - that is useful information. Documentation in the form of project planning documents, SOWs, data diagrams etc... - that stuff is always quite valuable, especially since it comes with an understanding that it was valid at a certain point in time (and may no longer be valid) but belies underlying decisions in how things were built and why.
- jonwest 3y agoThe only justification I can give to “$documentId - The ID of a document” style comments would be if they are alongside comments that actually give context. If there are 5 parameters, and 3 of them are helped with a bit of context, then adding superfluous comments to the other two makes sense because that in itself is a piece of documentation (parameters needed for a function or class). If all of your comments are like that though? Gross.
- karmakaze 3y agoWhen there's a complex bit of code, I expect to be able to `git blame` lookup the githash on GitHub and read the PR/issue description that should say what it's trying to achieve and how. I write PR descriptions expecting them to help years later.
- agumonkey 3y agoNew girl where I work did automated doc generation, good class coverage, gitlab wiki uploaded on CI. All alone. I was ecstatic.
- wheelerof4te 3y ago[flagged]
- t-writescode 3y agoThere’s far too much sexism in our industry for this to even begin to be a joke to be made, let alone that it shouldn’t be made in the first place.
- wheelerof4te 3y agoWhy is this sexism? It's a damn joke. If a woman made this same exact comment about "smashing" a male colleague, would you label it as sexist, too? Or are only men ever "sexist"?
- agumonkey 3y agoI do these joke daily on IRC but on HN I'd avoid. And sadly no, I'm not smashing anything.
- BSEdlMMldESB 3y agoso long as we can read the source code AND debug the program, it's ok. it may be difficult, but sometimes things are difficult free and open source but private and paid for documentation???
- zogrodea 3y agoThe React Flow library has free documentation, but more extensive tutorials on how to use their library are part of their paid offering. (More about their model here: https://reactflow.dev/blog/asking-for-money-for-open-source/ https://reactflow.dev/blog/asking-for-money-for-open-source/ .)
- BSEdlMMldESB 3y agothis actually may help me clear out a subtle distinction: the documentation has the same socialpolitical problem as any other artistic expression encoded into a digital asset but the code has a subtly different socialpolitical problem that goes a little bit further than the one of 'mere' digital assets. I don't expect to be understood, I just wrote this to think to myself... albeit in public.
- unconed 3y agoWhen people say documentation, they could mean: - a guide to the system to orient yourself - a reference for the api to look up in - tutorials to teach it - examples to copy/paste Each has a different audience and requires a different structure and writing style. I once spent a project being the lone wolf against my will, writing tons of documentation with diagrams. Didn't matter, if anything it just made the rest feel insecure and look bad. Everyone says they want docs but often they don't, really, because they don't read them when they do exist.
- scubbo 3y agoAmen! https://documentation.divio.com/ https://documentation.divio.com/
- hk__2 3y agoI started a new job at a small company 3 years ago and the very first thing I did was to create a central documentation repository, using Jekyll for some "fancy" rendering. All you have to do is dump your knowledge in a markdown file. There’s no hard convention; the goal is to have no barrier for entry. Three years later I can’t say that everybody uses it (I do!), but it has 176 pages in it, from infrastructure to how to run the company to things we learnt on the tech we use. Every time we lose time on a silly bug, we document it there so next time you can save the day with a Ctrl+F. All relevant dev or ops changes are documented here so when you notice some strange pattern in Grafana you can check the log and see that someone updated some config on that day. Every time there’s an incident in production we document how we fixed it. If tomorrow I leave the company, I know I’ll have very little to write down because everything is already there. The hard parts are: * not all people are willing to "waste" time filling the docs. It feels like wasting time but it’s always valuable for your future self as you won’t remember all the things you know today, and when someone joins the company you can point them to the docs instead of spending days explaining stuff * the more content you have the harder it is to keep it updated. We try to do it but in any case it’s in git so you can check the last commit to know if some content is old or not * having non-tech people contribute to it. At the beginning they had access to it but were a bit confused by Markdown. Now the marketing docs are in ClickUp (the tasks manager we use). We looked at Notion and similar solutions but for tech people there’s nothing better than a repository cloned on your computer in which you can grep * when you’re exhausted or frustrated because you spent the day on an issue, it can be hard to motivate yourself to document it. What I do is I keep a file open while I debug an issue and I write down what I do _as I do it_. That way all I have to do at the end is some formatting.
- mkl95 3y agoAt most companies the consensus is that if you want to understand the product, you need to master the code. Which can suck for legacy code that doesn't follow sane conventions.