32 ms·

Write documentation first, then build

219 points by maguay 4y ago

warning26 4y ago
This overlooks that doing things correctly tends to not be very fun. If you're working on a side project, I'd argue the best way to completely drain your motivation is to try and write a whole lot of documentation first.
- bruce511 4y ago
  With most creative endeavours about 20% is creative, the rest is work. This is why most side projects (what the rest of the world calls hobbies) never turn into anything commercial - because making it commercial means doing the work part. For example, writing a book. The writing part is easy, and fun. Then the work starts. First, second, third edits (or rewrites, depending on your definition of edit.) then finding (and convincing) an agent. Then ditto a publisher. (then more edits) Then endless book promotions in small book shops for 10 people at a time. If you're famous then tours on TV talk shows. Lots of boring travel, boring towns and boring work. If you want to write a book, write a book. If you want to be a writer expect to spend only a fraction of your time writing. If you're working on a side project, then do the fun part. Save the work for your employer. If you decide to turn your side project into your income, then you still get to do the fun part, but remember that success will require lots of work as well (like docs, examples, training and so on.) To be fair it's more fun doing work for the benefit if your own stuff - but work will be required.
- maguay 4y ago
  Author here. Agreed on doing things correctly tending to not be very fun. Would add that, for most people (writers, included), writing documentation isn't very fun, is often put off until the last minute, and easy to neglect since it's not fun. That's why I found it interesting to see how many examples of people writing documentation much earlier in the process, as it's an incentive to prioritize one of those not-fun tasks.
- mathgladiator 4y ago
  I find the opposite to be true. As I write, I think. As I think, more things become possible and I get excited.
daenz 4y ago
Docs should start out as a rough scaffolding that is easy to change, then filled in as the product anneals. The reason is that systems evolve as you build them, and constantly updating the docs to be consistent as the evolution occurs is an error prone chore that not everyone has the patience or diligence for. Assuming that your systems evolve as you create them, if you "complete" your docs too soon, you end up with less accurate docs than if you complete them later. Out of date docs are often harmful and demoralizing because they break trust.
- maguay 4y ago
  Author here, great point. Tony Fadell mentioned something similar in his Build book, about writing a press release before building your product. He mentions to pull the press release back out a few months into the project, and use the press release as a way to see what needs cut or what is critical to add. Or, if everything's changed too much, rewrite the press release. Scaffolding's a great example; it needs to morph as the project scope changes, but can also help set the scope (or at least direct it) at the start. At the very least, it gives you something to say ok, we're good to stop here, everything else can wait for v2.
- alex_suzuki 4y ago
  100% this. Outdated documentation is worse than no documentation. „Tell me you don’t care about your product without telling me you don’t care about it“. What I like to do is write a rough, high-level description of some core concepts that I don’t expect to change (they do, eventually). Just to get the ball rolling, and as a form of validation - if you can’t explain how something works, you either don’t understand it well enough or it‘s to complicated/convoluted.
- dmitriid 4y ago
  I've found out that "prototype fast, then document extensively as you re-write" a great approach. Because you've fleshed out the ideas, found out what works and what doesn't, and now you can capture all that in docs. However, as always YMMV and you might not get the luxury of re-writing :)
- b3morales 4y ago
captn3m0 4y ago
https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve...
drewcoo 4y ago
> VisiCalc started as a reference card. That appears to be false. This [1] tells how if they couldn't explain the feature on the reference card, they'd change the code. So the code came first. > The Nest thermostat started as a press release. From what I can tell, the product was announced in a Verge article[2] where there is a demo-able product. And the secret to their success, according to the article, was that it was designed by people who'd worked on phones. From what I can tell, actual product documentation came last in both cases, exactly as we'd expect. So the article starts with a double-barrel blast of bullshit. In the article's favor, they did write the bullshit down, though. [1] https://landley.net/history/mirror/apple2/implementingvisicalc.html https://landley.net/history/mirror/apple2/implementingvisica... [2] https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest-learning-thermostat https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest...
- maguay 4y ago
  Author here. The quote about VisiCalc starting as a reference card came from VisiCalc co-founder Dan Bricklin's TED Talk, where he mentioned writing the reference card first. And in the article you linked (which I'd also quoted from), Bob Frankston mentions the documentation card as part of prototyping, where it seems the card came first, and said "If we couldn't figure out how to explain a feature on the reference card we would change the program," which seemed to me another point towards documentation-drive development. And on the Nest thermostat, that story came from founder Tony Fadell's book, Build, where he says he wrote a press release before they started working on the Next thermostat. That would have been prior to The Verge's article, based on his story. Hope that helps clarify a bit.
  - GraemeMeyer 4y ago
    Fadell also spoke about this story on the Decoder podcast recently
  - CipherThrowaway 4y ago
    This is confusing to me. Did VisiCalc start as a reference card or not? Because the article doesn't say this and neither does the transcript of the TED talk. >In addition to prototyping, Dan put together a reference card for users. If we couldn't figure out how to explain a feature on the reference card we would change the program. The original method for copying formulas was too complicated so we just changed the design rather than try to explain it. Sounds like the reference card came after prototyping and was used as feedback in an iterative prototyping process. Pretty standard. This isn't "write before you code."
deleted 4y ago
[deleted]
DigitalSea 4y ago
So, in other words: write a specification document and then build. Isn't this what many reasonably run companies do anyway? There have been very few instances in my coding career where I've been asked to build something that didn't have a spec doc, design or some form of legwork done prior to implementation. A design I would argue is a form of documentation, visual documentation. The handful of situations where I've been asked to do something was a result of one boss in particular who was an ideas guy and would always come to me and ask me to build demos for ideas based on a few minutes of conversation.
- bruce511 4y ago
  In a team/large company context, yes - a spec gets made then some (usually someone else) gets to write the code. In a smaller context one, or two, people may be responsible for design and code. Assuming they have a good understanding of the problem space they may start with some practical things (like database design) then program, then document (if you're lucky) So, as with most things, context matters.
  - DigitalSea 4y ago
    You are completely right. Context definitely matters. The smaller team angle isn't something I thought about when I wrote my comment.
  - dgb23 4y ago
    If you work on client projects in a small team then a functional spec can help you keeping everything conceptual in one place and have a basis for discussion. It doesn’t have to be the most elaborate thing. A smaller project gets a few pages with some pictures, a more involved one has more explanation and database diagrams, a few stories and such. You do this work anyway, so why not write it down in a structured way? Pragmatic and simple but clear and neat. You’ll find that people do not tend to read every detail, but you can refer to the details when needed, which is very useful.
- arinlen 4y ago
  > Isn't this what many reasonably run companies do anyway? I love how the most basic of practices in any engineering field is depicted as a groundbreaking epiphany in the software industry.
oidar 4y ago
> Apple’s always taken documentation seriously Some might take exception to that.
LudwigNagasena 4y ago
Isn’t documentation written before building… just specification?
- marcosdumay 4y ago
  Yes, the article is arguing in favor of an iterated waterfall approach. As usual, some times this is a good choice. Even more if you choose a good iteration size.
aaronwalker 4y ago
I don’t know. I feel like there’s something to be said about building something on a limb because you’re curious and then seeing where it takes you. I feel like that approach, albeit less organized, can also lead to a great product because you end up naturally spending more and more of your time on a curiosity.
- jeffreygoesto 4y ago
  As one co-commenter wrote: it depends strongly on the context. From approx. 5 people up (to hundreds), starting with some whiteboard and constantly keeping up a joint documentation can help very much to split work and not step onto each other's toes... A good design document can be very short and much easier to understand than code, i.e. when you explain memory layout and do data oriented design.
alin23 4y ago
I guess that makes sense when you start a product specifically made to be sold. It’s good to have the end product as well defined as possible so you know how far ahead the end result is. But when “scratching your own itch”, docs would take away all of the ambition you started with because you might realize the scope of the project is bigger than you’d like. When I got my first monitor in 2017, I couldn’t believe that the only way to change its brightness throughout the day was to use a clunky joystick to go through the monitor menus and find the brightness setting, and press the joystick a million times to lower the brightness until it’s comfortable again. So I started to create Lunar (https://lunar.fyi https://lunar.fyi) with that in mind, an app that can automatically change the brightness of my monitor throughout the day. It was my first time doing a Mac app, my first time reading about DDC and my first time creating a desktop UI. If I had started with docs, that app would have never existed, because I would have realized just how much I didn’t know. Simply building it, bit by bit, led me to a good enough end result, that I could use myself and share with others, and no documentation was needed when the app did just one thing.
egithinji 4y ago
>“Writing is a way of finding out,” Quite often when drafting a question to a problem I'm facing, halfway through I'll discover the flaw in my reasoning or code.
farmin 4y ago
Yes but we all work differently. I love to come up with ideas as I build. It doesn't scale well with a team, but can allow you to be quite creative to start building something without everything planned. Maybe I am alone on this one.
picsao 4y ago
greggman3 4y ago
You'll find 100s or 1000s of article espousing the opposite. That you can't know what you want until you try building it. You can't see all of the issues and all of the problems and how your design really doesn't work until you actually try to build it. Imagine a chef trying to come up with a new dish. I suspect they don't write it down first. They mix things in and then see what to add to make it better. Sometimes they fail but don't think they'd get there by making cards. Cards are not the flavor and docs are not the actual product. Maybe it fits certain products more than others or maybe like everything it just depends, some projects succeed using the waterfall style, others need to improvise. Generally I think I prefer the iterate and edit style to the plan everything before you start style. But I also don't like wasting time so I'd prefer to spend as little time as possible going down paths that will be discarded. But often I think you can't know it's the wrong path until you get there.
- ng55QPSK 4y ago
  "You can't see all of the issues and all of the problems and how your design really doesn't work until you actually try to build it." - assuming you build something, nobody has tried to build before. In the 95% of other cases, use a library solutions, read about solutions that exist, try to learn from similar solutions. Don't reinvent the wheel. It's not wrong to do experiments, learn from that and apply the know-how to production code.
- misja111 4y ago
  > Imagine a chef trying to come up with a new dish. I suspect they don't write it down first. Many chefs do. Especially when it's about the presentation on the plate, many chefs make a sketch first before they prepare the new dish for the first time.
  - dgb23 4y ago
    Exactly! In my experience, a chef will do reasearch (they have a ton of notes/books/recipes), then combine some stuff and try things, but then will 100% write things down. Documentation is a key ingredient in cooking.
- 4y ago
allenu 4y ago
My opinion is this post romanticizes the idea of planning before building anything a little too much. As with anything, the devil is in the details. I agree that some type of high-level planning is needed before you do significant coding or design. However, just how much really depends on what you're building. I don't really buy into the notion that writing a lot first will get to the heart of what you want to build. There are far too many unknowns up front. You'll have to start prototyping and experimenting to really know if what you've planned has any merit in terms of a real product. What you've written will give you a map of where you're trying to go, but you'll need to be flexible enough to change some of those initial plans if reality doesn't match your expectations.
- andi999 4y ago
  UML left the room..
- dgb23 4y ago
  When you can’t write a functional spec of something, then exploration/prototyping is in order. But that doesn’t mean you shouldn’t write one when you can. It’s very useful to get people on literally the same page.
andmarios 4y ago
I think the word documentation is not used correctly in the article. The article seems to suggest small snippets of text, ranging from one short paragraph to a few pages. It also goes on to explain documentation as memo / press release / reference card. But all these are not documentation. It sounds like the PRFAQ method, which is already in use by many teams. It's good, especially because it aligns people across all verticals of a company.
self_awareness 4y ago
It's not about using the pen and paper before the build. It's about building prototypes before the actual product. There's nothing wrong with prototyping the software using code and building it directly. The problem is when the prototype is being automatically elevated to a product rank when it starts working. In such case, everyone treats the prototype as it were a product, but in reality it's still a prototype. So instead of using pen & paper, just use the code to prototype things, because it's 2022 and it's possible to do so. Just make sure to properly transform the prototype into a full-fledged product when the time comes, possibly by rewriting the implementation, maybe even change the implementation language (e.g. Python for prototyping, C++ for implementation).
brzezmac 4y ago
So we have come full circle. That's the way we have been building software when I was starting with professional software development (this was around 2005). But the idea of doing a thorough analysis (business, technical) is a little bit older. The only people to whom this might come as a surprise are the ones who've drank too much of the "agile Kool-aid". I'm not here to bash agile and start this flame war all over again (agile has it's merits ...), but somehow thinking before doing got a bad rap recently (for reasons beyond me). It's like software development got trapped inside of King Julian's (from Madagascar movies/series) brain with his modus operandi: "let's start doing this before we figure out it does not make any sense".
- shreyshnaccount 4y ago
  Because thinking clearly is the hard part. I use Github copilot every day for work (and it generates decent code completion for me) and the only thing I've realised is that the major work in programming is to think clearly, and converting thoughts to syntax is not really that hard. Copilot takes off that easier cognitive workload and helps me focus and clear my thoughts. Also, does anyone know how to think clearly or does that just come with practice and experience?
  - brzezmac 4y ago
    Thinking, especially abstract thinking, is crucial to software development, as often (not always) creating software is abstracting real life into algorithms and data structures. Writing text in a word procesor, notepad, etc. is in my opinion first step to validation of the idea, to having at least faint idea about the complexity of the solution we would like to build. On the question of "how to think clearly" - I'd say it's pretty individual - some people start "from the bottom", some "from the top" and others "in the middle". Experience is to know which is which and which approach suits you best.
    - shreyshnaccount 4y ago
      Wise words. That's prolly why you need to be good at math to be good at tech, abstract thinking all the way
toolslive 4y ago
Actually, you can do both at the same time: write a functional spec that you can run to see if it's correct. https://www.researchgate.net/publication/2468505_Functional_Specification_of_JPEG_Decompression_and_an_Implementation_for_Free https://www.researchgate.net/publication/2468505_Functional_... The idea never caught on.
- ubercore 4y ago
  My first job out of college was working for someone that wanted to implement whole systems in XML documents and use XSLT transforms to turn them into working code and documentation at the same time. That approach didn't last very long. But hey at least I learned the Muenchian Method.
  - toolslive 4y ago
    xml is not a programming language, haskell (actually Gofer) is. I guess that was part of the problem.
    - ubercore 4y ago
      There were a lot of problems...
dusted 4y ago
If I'm writing some small tool, I often start with fictional workflow examples.. These get adjusted as I discover ways that the implementation can be made simpler or easier without any significant changes to the workflow.. Other times I find that the workflow is annoying and that a larger complexity in the implementation is well worth it for a nicer workflow.. What I'm trying to convey is that it's often better to BOTH have a lose idea of how it should be used AND how to implement it, but be ready and able to change both implementation and workflow/documentation as new discoveries are made.. In the end, if you know the implementation AND workflow EXACTLY, it's because the program already exists and you should just use that instead..
bajsejohannes 4y ago
> Writing is a way of finding out Writing _code_ is also a way to find out.
jpswade 4y ago
I think "Working Backwards: Insights, Stories, and Secrets from Inside Amazon" by Bill Carr puts this better. Their idea is that you start with what the press release might be, something everyone can get excited about, and then work backwards from that.
singularity2001 4y ago
One problem for me is that I lose motivation after writing the documentation, thinking that burdensome implementation of the details should be left as an exercise to others.
- dgb23 4y ago
  That’s a dangerous notion, because you might be overestimating your ability to think things through in detail. It’s typical to revist a spec and iterate on it. Also a program literally is a specific spec for a given computing environment, and there are often many interesting things to figure out.
hazelnut-tree 4y ago
I like the documentation first approach, but I understand that it does not work for everyone. Designing a program (on paper or the screen) before you start coding is still the recommended textbook approach from university courses and books. I think of documentation in the broadest form. For example, flow diagrams, or rough wireframes of screens in your app. Figma (and other tools) is good for creating rough app prototypes with short annotations describing features. You get the benefit of fleshing out flows and screens or pages (before coding) but without heavy documentation. A popular UX technique you can try by yourself (or with colleagues) called 'Design The Box' can also be used before you start coding. It's an exercise to articulate the key features and benefits of your app: https://gamestorming.com/design-the-box/ https://gamestorming.com/design-the-box/
BiteCode_dev 4y ago
This advice works only if 5 prerequisites are met: - the coder is fluent in programming. Beginners will not know how to architecture things, and need to fiddle way more. It's impossible for them to create a doc that will make sense from the top of their head. - The coder understands the problem well, and it has a known solution. Many problems are better understood when trying to solve them, by exploring its space while programming. It's impossible to start documenting something you don't know very well. It's espacially true if you have to come up with a novel solution. - The problem is well defined. Unlikely. Clients don't define their problem well, and it's half our job to extract the information from their brain. However, while it is sometimes possible to get that on paper, and formalize it, most of the time, programming an incorrect PoC and iterating on it is a better interface to communicate with the client: they have a visual result to discuss. Writting a doc that you trash down every day would be a waste. - The coder understands the field well. I'm currently working with a Bank, and I don't know the field. Many algo I must implement are in the head of my clients, and the quickest road to understanding them is to peer code them. They attempted to make a formal doc first of course. After 6 months, they still don't agree on how to do some things. One week of coding with me forced them to confront reality, and take concrete decisions. - The coder has the big picture. Starting with a doc assumes you know what your API should look like. I would recommand that you do know, if you don't, you are probably in trouble. But it's a fact of life that sometimes you can't figure it out, and starting from something incomplete and coding it will make the big picture clearer. That's a lot of pre-conditions. My experience is that most teams starting with the doc (or tests) don't ship, or end up shipping only once they start fiddling. Those who do are excellent teams, the best ones, and I love working with them. But they are a rare bread. We are usually an average team, not ticking all pre-conditions, and not composed of only very skilled or experienced professionals. We fiddle a lot. And unless you have a great team leader, taking such an ordinarity team and making it write the doc first will result in a terrible doc that doesn't match the solution to the problem, that you will rework again and again, while nothing is getting in the hand of the client for concrete feedback. I favor a middle ground: start with paper, but don't pretend you are going to have a full spec.
somishere 4y ago
I mean yes, but also no way. I think the term 'documentation' (in a dev context anyway) is a daunting one. Documentation is hard. Time is poor. And things always change in build, often big things. Knowing the process, why would you presume the outcome? That said, even on personal projects I do like to write a readme.md (a scope of work "lite" - audience me) outlining the intention and key features of whatever it is I am planning to create. This isn't a massive commitment, neither detailed nor prescriptive, but it does provide a reasonable amount of guidance and milestones. But it's not documentation.
drunkenmagician 4y ago
Hmmm, I think it depends on how much documentation. Design docs are important to clarify and communicate the intent. But typically (at least in my personal experience), designs evolve during the implementation as better understanding and consideration of edge cases comes to light. I now personally favour light weight PoC projects for any non trivial development projects.
anotheraccount9 4y ago
Instead, some sort of visual documentation, showing the milestones and fundamentals of what is expected.
phforms 4y ago
I think the process highly depends on what you know about the requirements and what is unknown. More established and standardized fields like mechanical engineering already know a lot of things upfront and can specify/document what the project is supposed to implement without having to tinker and experiment first. That may also be true for some types of products in SE that have been built hundreds of times before or some types of problems that we already know how to solve. But with many other projects, a lot of uncertainty comes along, where we don’t even know what we don’t know yet. In these cases it can be a great waste of time and energy to try and fix design decisions upfront, based on a theory of how things supposedly will work. In my experience, a lot of important insights can only be generated while you operate with the matter at hand (or at least imagine doing so, but this is very hard and inaccurate in more complex cases). Therefore, I believe that doing small, isolated experiments/prototypes before writing any documentation (and certainly before writing production-level code) is a crucial first step that should not be avoided unless you have a very solid understanding of what you’re about to build. I agree, however, that we shouldn’t start coding for production before doing any sort of research and design step first (although I don’t think that it is a linear process – we might have to cycle through these stages repeatedly). I have worked in graphic design for many years before doing SE and my more challenging projects always needed multiple practical experiments – planning everything in my head upfront never got me anywhere. Of course, GD and SE cannot be compared 1:1, but both involve research and design. Of course, planning experiments can still be fruitful and it certainly helps to formulate scope and intent beforehand so you know what problems you are trying to solve (this is how I would see the role of the press release mentioned in the article). For more complex, long-term projects, I like to keep a dev journal where I can document my research and approaches while working on experiments and prototypes. This helps me a lot later on to re-trace my thinking process and the act of writing certainly helps to organize and focus my thoughts. I don’t think of this as a techical documentation/specification, but maybe it is one of the things the author of this article had in mind.
lakomen 4y ago
I don't know... When I start something new it's often spontaneous. I have this idea I'd like to try and then I start hacking. And while I hack at the keyboard and create the basis I think of the long term. Having to do double work, write a document first and then repeat the same in code is extremely counterproductive. Motivation plays a big role. Repetition is not fun. Most projects never get finished. There are always obstacles and some are really hard. But you won't know them from writing documentation alone. And if you write documentation ahead of time it's very likely this documentation will not fit the final product, at 1st release time. Having a general outline with key features is ok. But fully-fledged documentation is over the top. That's my educated opinion at least. Motivation is very important for me, especially if I don't know for years if this thing I'm building will be used by people at all. Single developer. If there were dedicated people for tasks, that'd be different, probably. Also you can't take the established business and say they all had a memo or document and that's the reason why they succeeded. That's a really long shot, IMHO.
- tuxie_ 4y ago
  I completely agree with your point here. As I wrote in a previous comment for a different post: I'm currently developing an "experimental" piece of software, i.e. I am not even sure some features I want to add are possible, meaning I had to rewrite it a couple of times (and won't be the last). Having strict versioning, pinning, and documenting everything before it reaches a semi-stable state would discourage me from developing it altogether.
- geek_at 4y ago
  So true, when I say in engineering school we had a subject called project management and we were taught that you have to write the documentation and everything first and it should be done in such a detail (including variable names and such) that you can give the project documentation to three different programmers and receive the exact same product from all three. I always hated this approach because of the reasons you stated. I love the quote from that German hacker Fefe: "Coding is an explorative process"
  - quickthrower2 4y ago
ajani 4y ago
I tend to do the exact opposite. Only when the program is fully done (if ever) do I document it (beyond peppered lines of documentation that explain something that is not obvious from code). There is good reason for this: Premature abstraction. As others have pointed out when I start to work on an idea, I’m not sure about everything. Working on it will reveal misassumptions and blind spots in my current thinking. I have also learned to abstract out behavior into functions lazily. Often having created defined functions with an immaturely developed idea is a hindrance to flexible experimentation.
samsquire 4y ago
I must agree with this. I understand algorithms more after I write down what they actually mean or do and why. The implementation is secondary. I would rather read what an algorithm does than read your implementation. Even though the implementation is more useful from an execution perspective. From the description I can write my own. It's easier for me to understand a plain description of an algorithm or technology than the code that implements it. Reading code is an investment. Reading code is harder than reading English of the same..I understand that English is imprecise but from a detailed description of say the Chrome layout engine I could probably learn how to write a layout algorithm but the documentation for layout algorithms doesn't exist in a digestible form so you are forced to read Chromium sourcecode. The ORC whitepaper uses branch and bound optimisation technique paired with a constraint satisfaction optimiser. I suspect I can use ORTools. How many alternative rendering engines are there really? IMGUI, video game layout engines and video game engines, Gecko, Blink, WebKit and JavaFX and Swing and Qt QML
vintagedave 4y ago
Like some other commenters, I disagreed with the headline. But the article says something more subtle than 'write documentation first'. Its points are: * Write documentation alongside, ie as you go * Use writing English (or your language) documentation as a way to clarify your thoughts: the process of writing is a tool to ensure something is well thought through I disagreed with the headline because I interpreted it as writing end-user documentation, effectively a very detailed specification document, up-front and then writing code to match. In reality, coding is a process of discovery, and you need the flexibility to allow the implementation to change. Your goal might be known, but the path to that goal is flexible. The article pitches writing that goal upfront. Visicalc had a few sample formulae. Nest had a press release written. But for both, and it's explicitly called out for Visicalc, the actual user-facing documentation was written alongside the code as the product developed. This solves the problem of not having documentation ready when the product is ready, too. In short: misleading headline, insightful article. I'd like to take its suggestion of writing docs alongside implementation as implementation develops on board myself.
plaguepilled 4y ago
Yes yes yes a million times yes. I need this engraved into the skull of every tech lead that claims the code is the documentation. The engraving will be appropriately referenced. It will also link to another engraving that documentation is good actually.
leetrout 4y ago
I like this because I value alignment. Writing (and meetings) offer the chance to get aligned.
- nawgz 4y ago
  But how can writings and meetings align code that doesn't yet exist? Are you a believer that during writing of documentation, you can anticipate each code challenge and solve it ahead of time?
  - leetrout 4y ago
    Alignment of humans. Their intents and expectations.
nottorp 4y ago
Someone rediscovering waterfall?
Simplicitas 4y ago
Good luck convincing management of that.
papito 4y ago
So one camp says "just jump in and code", the other one advises to go full waterfall and write books of documentation. Yet again, the new generation is making the same mistakes us fossils learned from years ago. You will be shocked to find out that the truth is in the middle. "Jumping in an hacking" is a recipe for a waste of life (but seems fine when you are young and the time seems eternal). Yes, you will eventually get it done, but after going down rabbit holes and "just getting it to work", you will end up with code that, let's just say, down the road you will not be proud of. Trying to think everything through in advance is a fool's errand. Your "documentation" will be useless after you write the first few lines of code, unless you are clairvoyant and can predict every little problem. Think before you write, that's all. Think more, write less. I spend more time thinking about what I am about to write, but at some point I have to start coding, before I enter the analysis paralysis stage.
_gabe_ 4y ago
> So when Bezos—in a possibly apocryphally, 128-word memo—wrote that “All teams will henceforth expose their data and functionality through service interfaces,” it was a focused idea that led to Amazon building web services for which it’d be it’s own best customer, and turned AWS into the cloud computing juggernaut it is today. Last I checked, almost every AWS api has a V2. And wait, I just checked, AWS CDK is on V2.28.0. I wonder why the last 28 versions of V2 didn't work if they wrote the documentation first? Last I checked, Mac OS is on like version 11 or something? I'm not a Mac user so I don't follow this stuff. Clearly, documentation is not a silver bullet. If it was, we wouldn't have to continue to rewrite and bump the versions of all of our tools. When I worked at Amazon, writing that 6 page document was like agonizing torture. They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that?? I don't know what other APIs I may or may not have to call to actually get this to work. Implementation details matter a lot. I don't remember who said this, but there's a saying that's something like ideas are worth nothing. Execution is worth everything. And the same thing goes for documentation, what good is documentation without a final product? It's useless.
- sumy23 4y ago
  > They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that? Isn’t that part of the job? When writing a technical document, you need to research things like dependencies, data storage, caching and estimate expected latency.
  - _gabe_ 4y ago
    The only way to get an accurate estimate of expected latency is to measure it in all sorts of different scenarios. You can't measure something that doesn't exist. And relying on other peoples documentation for accurate latency estimates is asking for trouble. The one thing I've learned through profiling a lot of my code is that my intuitions about how long something will take are always wrong.
    - sumy23 4y ago
rubyist5eva 4y ago
As someone who just got promoted into engineering management from development, the number one cause of frustration, delays, confusion was always lack of documentation - either in requirements or just how the system works in general. It’s now my number one priority to ensure that we have a proper framework for documenting requirements ie. no more two-line “change this functionality because reasons” tickets and having a centralized wiki that documents all features and how the work, along with any quirks that exist.
rmbyrro 4y ago
This is good advice especially for developer tools. Start with the API interface first: 1. Ask what problems the tool intends to solve 2. Then ask what's the best experience for developers to command or program it "Best experience" depends on the context. A few factors worth consideration are: - Succinctness - Easiness to understand - Memorability - Clarity - Familiarity (if developers are already used to some existent API) Then build whatever is needed to make that API get developers from point A to point B.
bitwize 4y ago
I find that the quality of my output tends to increase if I'm Literate Programming. And in that regard, documentation is like testing: whether you do it first or second doesn't matter as long as you do it and integrate it into your process. I tend to find that I'm chasing an idea and hacking code together without updating the docs. Then I hit a complexity wall and go back and look at the big ball of mud I made, and break it into pieces, updating the documentation for each piece, and then I get a refactor idea that helps me simplify the code.
pete_nic 4y ago
I feel like a more appropriate name would be “write first, then build”. “Documentation” reminds the product managers and engineers of corporate-y documents like release notes. The “documentation” described is more of a fluid collection of ideas than what we would consider “documentation”. I have found this to be true - “Writing is a way of finding out”.
linsomniac 4y ago
"The sooner you start to code, the longer the program will take."
- marcosdumay 4y ago
  Just like "two programmers can always achieve in two months what takes an entire month for a single programmer", the one we imported from sciences "a short week programming can save you many hours of thinking", and other similar famous phrases, this is true when it is; when it isn't, it's false.
zugi 4y ago
Aren't we supposed to write unit tests before we build too? The benefit of that is that if you have a CI system the tests have to stay current with the code. Whereas documentation quckly gets out of sync with the actual code.
boredumb 4y ago
If you're best at designing and building front ends, go build that first and plug into an API later. If you're best at writing backend code and APIs, go build that first and plug in your front end later. If you're best at writing docs and speccing, go build that first and then iterate through the two items above.
stefanve 4y ago
I can't remember the last time I worked somewhere where nobody wrote down anything. Sure sometimes not enough and sometimes too much. But in general people write down specs in, stories, tasks, pitches, presentations, wireframe, slick UIs etc. Even for my own play projects I generally start out with an outline of some sorts. but total spec upfront brings back bad memories from the waterfall world. But I have also had discussions with folks who thought that agile means not specs/documentation at all
voidhorse 4y ago
Tangential to the article but I’m curious to see what the app looks like once it releases. I’ve been thinking a lot recently about how software for editing text (not authoring) is woefully unexplored. When it comes to other mediums like video, software has maintained the film/edit division—one captures video with a camera then uses dedicated software to edit it. It remains a two-step process and the division between steps is reinforced by the design of supporting software. With writing, the opposite has happened. Software helped collapse the two-step divide between writing and editing. Text editors serve a dual purpose in that one can both produce the initial content and edit it thereafter all at once and seamlessly, in one tool, in one session. However, I remain convinced this is a bad way to do it and the two-step approach is the correct one. It’d be interesting to see what a tool dedicated only to the editing phase could look like (so, you can alter existing text but cannot use it to produce novel material).
- bradrn 4y ago
  > It’d be interesting to see what a tool dedicated only to the editing phase could look like (so, you can alter existing text but cannot use it to produce novel material). Scribus [https://www.scribus.net/ https://www.scribus.net/] specifically states that it’s meant for editing already-written text; I’d imagine that other publishing software (e.g. InDesign) works fairly similarly.
beshur 4y ago
My grandpa worked like this on a naval propulsion factory :) They had quite a long development lifecycle - decades for every new engine from inception to series production.
ChrisMarshallNY 4y ago
I've had a great deal of experience with the "Measure Twice, Cut Once" approach. Most of my career was at hardware companies, and hardware development tends to be about as Waterfall as you can get. It was incredibly frustrating, because they insisted that software be developed the same way as hardware. Efforts to tell them that software is different were met with sneers, and accusations of being "lazy," or "sloppy." The OP was done by a professional writer, so it's not surprising they have a "documentation-first" approach. I tend to use an approach I call "Forensic Design Documentation"[0], and "Evolutionary Design"[1]. Knowing what you want is not easy. That's the single biggest problem with a "requirements-first" approach. I've learned the value of rapid prototyping, and getting involvement from non-tech stakeholders, as early as possible, so the project design is iterative, and hands-on. But there was this chap named Damocles, and his sword is often brought up, in situations like this... "Rapid prototyping" is often taken as license to do sloppy work. The single biggest issue with rapid prototyping, is that management always assumes that the project is "done," and cut the schedule and budget, forcing you to use the junk prototype as the ship product. After a couple of these, I learned to make my prototypes top-quality, if functionally incomplete. That way, by the time management says "f**k it, let's ship!", the project is actually shipshape. And I am careful about documentation. I tend to use a lot of embedded documentation (headerdoc-style)[2]. That's because it "ages" well, and tends to be a lot less of a "concrete galosh."[3] [0] https://littlegreenviper.com/miscellany/forensic-design-documentation/ https://littlegreenviper.com/miscellany/forensic-design-docu... [1] https://littlegreenviper.com/miscellany/evolutionary-design-specification/ https://littlegreenviper.com/miscellany/evolutionary-design-... [2] https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ [3] https://littlegreenviper.com/miscellany/concrete-galoshes/ https://littlegreenviper.com/miscellany/concrete-galoshes/
- jstimpfle 4y ago
  How do you make prototypes top-quality? Unless you know what you want, isn't it hard to make the best shape for that thing?
  - ChrisMarshallNY 4y ago
productceo 4y ago
Always the right approach and only the right approach
hoosieree 4y ago
For work projects, I often write a short README file first, and share it with my team as a sanity check before writing a single line of code. It's just rough draft which says "here is the problem I think we are solving, and why/how we're solving it". If my team has feedback, I update the README. This is easier to keep track of than Slack conversations. If necessary, this document can be polished later, when other people need to use the thing we built. But it's nice to have a starting point.
bern4444 4y ago
A company I was at followed this approach. But of course putting it in writing then meant it had to be shared and approved or "reviewed"(reviewers of course thought they were approvers which was never the case). We called them TDDs (Technical Design Documents) and they were a nightmare. The docs were often out of date, as the actual engineering would deviate strongly over time (and short periods of time too, like days). They were incomplete as we wouldn't quite know what was involved until we actually began figuring it out by writing code and building POCs. We also wouldn't know how far we'd want to take some decisions until we had code to then figure out questions about share-ability, extensibility, ownership, etc. The project would take significantly longer as everyone would first work on the TDD before ever working with code. Then you'd have to corral approvals which involved comments, questions, and a lot of back and forth. This would take days and could stretch out into weeks. All in all it became a PITA and I wouldn't care to ever continue this practice. I agree writing helps clarify intent and understanding, for software that writing comes through by writing code. Phrases like measure twice and cut once don't really make sense for software where getting new wood to cut has an effective marginal cost of 0. Software is completely different from any physical good so these analogies just don't make sense. It's not like a building where once it's built it's impossible or difficult to change. We can forever update, improve, repurpose, and clean up any and all aspects. Write a README or a TDD once the project is done to capture how it works, the problem being solved, or any gotchas, limitations, or ideas for future development. But this should go at the end. Lean in to software's strength of exceptional flexibility and adaptibility and stop treating it like a physical thing.
atx42 4y ago
Always upvote articles that imply Agile can be lacking. Really, meta-processes are the way to go, and can be defined by checklists. E.g. For this effort, will documentation be helpful? check yes/no. Then you aren't blindly just doing stuff because it is or is not part of the process. The process itself is configurable.
JonChesterfield 4y ago
Build first. Then write down what you should have built. Then build that thing second. All documentation first wins you is documentation to throw away along with the first revision.
- b3morales 4y ago
  You can (should) extend this forward too! Build a mockup, write a doc describing that, then write a rough implementation, revise, and so on.
SenHeng 4y ago
I just happened to be reading up on Readme Driven Development[0] last night and the HN thread[1] had a few mentions of Donald Knuth's Literate Programming[2]. Fascinating read. [0]: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve... [1]: https://news.ycombinator.com/item?id=17427593 https://news.ycombinator.com/item?id=17427593 [2]: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming
spurgu 4y ago
A lot of good ideas come through trial and error. After a certain while of using a product a specific way whole new pathways can open up. It's really difficult to know what your end product is supposed to look like, if you're working on something novel. If you're building something that already exists, sure, then you can structure and optimize it during the design phase (and should).
mihaigalos 4y ago
I see tests as executable documentation/specification. TDD reinforces that view. i.e. rust even has the specification of parts of its functionality using asserts (in the docs): https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#examples https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#exa...
lr1970 4y ago
IMHO, the process of software project development is iterative and non-linear. Writing some docs followed by some code, then writing/editing more docs, then more code, tests, experiments ... rinse and repeat. I found that any rigid structure like docs-before-code or code-before-docs to be counterproductive.
AtlasBarfed 4y ago
This is worse than TDD "write the test first" extremism. The # of projects that have all the requirements perfectly laid out to enable this is... effectively zero. I can see something where the requirements and iteration/convergence artifacts lead to some structured documentation ... maybe, that's an interesting idea. The reason documentation comes last is that you don't know what comes out the end of the sewer pipe after the vagaries of Faster, Better, Cheaper pick two... well actually it's Faster Better Cheaper Documented ProcessFollowed, pick 2.5.
elesbao 4y ago
I like the idea of at least writing a PR and FAQ (where a build is a product). That helps a lot fo manage anxiety and kill backlogs.
charliepark 4y ago
Small correction: you mention the Apple documentation specialist Jef Raskin, but you spelled his name with two “f”s; his name only had one.
pipeline_peak 4y ago
Cobble together stackoverflow code, don’t write docs, instead hire entry level devs to fix the cryptic levels of technical debt in your code, reward them with seniority for how long they endured.
main3523 4y ago

219 points by maguay 4y ago

This overlooks that doing things correctly tends to not be very fun. If you're working on a side project, I'd argue the best way to completely drain your motivation is to try and write a whole lot of documentation first.

bruce511 4y ago
With most creative endeavours about 20% is creative, the rest is work. This is why most side projects (what the rest of the world calls hobbies) never turn into anything commercial - because making it commercial means doing the work part. For example, writing a book. The writing part is easy, and fun. Then the work starts. First, second, third edits (or rewrites, depending on your definition of edit.) then finding (and convincing) an agent. Then ditto a publisher. (then more edits) Then endless book promotions in small book shops for 10 people at a time. If you're famous then tours on TV talk shows. Lots of boring travel, boring towns and boring work. If you want to write a book, write a book. If you want to be a writer expect to spend only a fraction of your time writing. If you're working on a side project, then do the fun part. Save the work for your employer. If you decide to turn your side project into your income, then you still get to do the fun part, but remember that success will require lots of work as well (like docs, examples, training and so on.) To be fair it's more fun doing work for the benefit if your own stuff - but work will be required.
maguay 4y ago
Author here. Agreed on doing things correctly tending to not be very fun. Would add that, for most people (writers, included), writing documentation isn't very fun, is often put off until the last minute, and easy to neglect since it's not fun. That's why I found it interesting to see how many examples of people writing documentation much earlier in the process, as it's an incentive to prioritize one of those not-fun tasks.
mathgladiator 4y ago
I find the opposite to be true. As I write, I think. As I think, more things become possible and I get excited.

daenz 4y ago

Docs should start out as a rough scaffolding that is easy to change, then filled in as the product anneals. The reason is that systems evolve as you build them, and constantly updating the docs to be consistent as the evolution occurs is an error prone chore that not everyone has the patience or diligence for. Assuming that your systems evolve as you create them, if you "complete" your docs too soon, you end up with less accurate docs than if you complete them later. Out of date docs are often harmful and demoralizing because they break trust.

maguay 4y ago
Author here, great point. Tony Fadell mentioned something similar in his Build book, about writing a press release before building your product. He mentions to pull the press release back out a few months into the project, and use the press release as a way to see what needs cut or what is critical to add. Or, if everything's changed too much, rewrite the press release. Scaffolding's a great example; it needs to morph as the project scope changes, but can also help set the scope (or at least direct it) at the start. At the very least, it gives you something to say ok, we're good to stop here, everything else can wait for v2.
alex_suzuki 4y ago
100% this. Outdated documentation is worse than no documentation. „Tell me you don’t care about your product without telling me you don’t care about it“. What I like to do is write a rough, high-level description of some core concepts that I don’t expect to change (they do, eventually). Just to get the ball rolling, and as a form of validation - if you can’t explain how something works, you either don’t understand it well enough or it‘s to complicated/convoluted.
dmitriid 4y ago
I've found out that "prototype fast, then document extensively as you re-write" a great approach. Because you've fleshed out the ideas, found out what works and what doesn't, and now you can capture all that in docs. However, as always YMMV and you might not get the luxury of re-writing :)
b3morales 4y ago

captn3m0 4y ago

https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve...

drewcoo 4y ago

> VisiCalc started as a reference card. That appears to be false. This [1] tells how if they couldn't explain the feature on the reference card, they'd change the code. So the code came first. > The Nest thermostat started as a press release. From what I can tell, the product was announced in a Verge article[2] where there is a demo-able product. And the secret to their success, according to the article, was that it was designed by people who'd worked on phones. From what I can tell, actual product documentation came last in both cases, exactly as we'd expect. So the article starts with a double-barrel blast of bullshit. In the article's favor, they did write the bullshit down, though. [1] https://landley.net/history/mirror/apple2/implementingvisicalc.html https://landley.net/history/mirror/apple2/implementingvisica... [2] https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest-learning-thermostat https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest...

maguay 4y ago
Author here. The quote about VisiCalc starting as a reference card came from VisiCalc co-founder Dan Bricklin's TED Talk, where he mentioned writing the reference card first. And in the article you linked (which I'd also quoted from), Bob Frankston mentions the documentation card as part of prototyping, where it seems the card came first, and said "If we couldn't figure out how to explain a feature on the reference card we would change the program," which seemed to me another point towards documentation-drive development. And on the Nest thermostat, that story came from founder Tony Fadell's book, Build, where he says he wrote a press release before they started working on the Next thermostat. That would have been prior to The Verge's article, based on his story. Hope that helps clarify a bit.
- GraemeMeyer 4y ago
  Fadell also spoke about this story on the Decoder podcast recently
- CipherThrowaway 4y ago
  This is confusing to me. Did VisiCalc start as a reference card or not? Because the article doesn't say this and neither does the transcript of the TED talk. >In addition to prototyping, Dan put together a reference card for users. If we couldn't figure out how to explain a feature on the reference card we would change the program. The original method for copying formulas was too complicated so we just changed the design rather than try to explain it. Sounds like the reference card came after prototyping and was used as feedback in an iterative prototyping process. Pretty standard. This isn't "write before you code."

deleted 4y ago

[deleted]

DigitalSea 4y ago

So, in other words: write a specification document and then build. Isn't this what many reasonably run companies do anyway? There have been very few instances in my coding career where I've been asked to build something that didn't have a spec doc, design or some form of legwork done prior to implementation. A design I would argue is a form of documentation, visual documentation. The handful of situations where I've been asked to do something was a result of one boss in particular who was an ideas guy and would always come to me and ask me to build demos for ideas based on a few minutes of conversation.

bruce511 4y ago
In a team/large company context, yes - a spec gets made then some (usually someone else) gets to write the code. In a smaller context one, or two, people may be responsible for design and code. Assuming they have a good understanding of the problem space they may start with some practical things (like database design) then program, then document (if you're lucky) So, as with most things, context matters.
- DigitalSea 4y ago
  You are completely right. Context definitely matters. The smaller team angle isn't something I thought about when I wrote my comment.
- dgb23 4y ago
  If you work on client projects in a small team then a functional spec can help you keeping everything conceptual in one place and have a basis for discussion. It doesn’t have to be the most elaborate thing. A smaller project gets a few pages with some pictures, a more involved one has more explanation and database diagrams, a few stories and such. You do this work anyway, so why not write it down in a structured way? Pragmatic and simple but clear and neat. You’ll find that people do not tend to read every detail, but you can refer to the details when needed, which is very useful.
arinlen 4y ago
> Isn't this what many reasonably run companies do anyway? I love how the most basic of practices in any engineering field is depicted as a groundbreaking epiphany in the software industry.

oidar 4y ago

> Apple’s always taken documentation seriously Some might take exception to that.

LudwigNagasena 4y ago

Isn’t documentation written before building… just specification?

marcosdumay 4y ago
Yes, the article is arguing in favor of an iterated waterfall approach. As usual, some times this is a good choice. Even more if you choose a good iteration size.

aaronwalker 4y ago

I don’t know. I feel like there’s something to be said about building something on a limb because you’re curious and then seeing where it takes you. I feel like that approach, albeit less organized, can also lead to a great product because you end up naturally spending more and more of your time on a curiosity.

jeffreygoesto 4y ago
As one co-commenter wrote: it depends strongly on the context. From approx. 5 people up (to hundreds), starting with some whiteboard and constantly keeping up a joint documentation can help very much to split work and not step onto each other's toes... A good design document can be very short and much easier to understand than code, i.e. when you explain memory layout and do data oriented design.

alin23 4y ago

I guess that makes sense when you start a product specifically made to be sold. It’s good to have the end product as well defined as possible so you know how far ahead the end result is. But when “scratching your own itch”, docs would take away all of the ambition you started with because you might realize the scope of the project is bigger than you’d like. When I got my first monitor in 2017, I couldn’t believe that the only way to change its brightness throughout the day was to use a clunky joystick to go through the monitor menus and find the brightness setting, and press the joystick a million times to lower the brightness until it’s comfortable again. So I started to create Lunar (https://lunar.fyi https://lunar.fyi) with that in mind, an app that can automatically change the brightness of my monitor throughout the day. It was my first time doing a Mac app, my first time reading about DDC and my first time creating a desktop UI. If I had started with docs, that app would have never existed, because I would have realized just how much I didn’t know. Simply building it, bit by bit, led me to a good enough end result, that I could use myself and share with others, and no documentation was needed when the app did just one thing.

egithinji 4y ago

>“Writing is a way of finding out,” Quite often when drafting a question to a problem I'm facing, halfway through I'll discover the flaw in my reasoning or code.

farmin 4y ago

Yes but we all work differently. I love to come up with ideas as I build. It doesn't scale well with a team, but can allow you to be quite creative to start building something without everything planned. Maybe I am alone on this one.

picsao 4y ago

greggman3 4y ago

You'll find 100s or 1000s of article espousing the opposite. That you can't know what you want until you try building it. You can't see all of the issues and all of the problems and how your design really doesn't work until you actually try to build it. Imagine a chef trying to come up with a new dish. I suspect they don't write it down first. They mix things in and then see what to add to make it better. Sometimes they fail but don't think they'd get there by making cards. Cards are not the flavor and docs are not the actual product. Maybe it fits certain products more than others or maybe like everything it just depends, some projects succeed using the waterfall style, others need to improvise. Generally I think I prefer the iterate and edit style to the plan everything before you start style. But I also don't like wasting time so I'd prefer to spend as little time as possible going down paths that will be discarded. But often I think you can't know it's the wrong path until you get there.

ng55QPSK 4y ago
"You can't see all of the issues and all of the problems and how your design really doesn't work until you actually try to build it." - assuming you build something, nobody has tried to build before. In the 95% of other cases, use a library solutions, read about solutions that exist, try to learn from similar solutions. Don't reinvent the wheel. It's not wrong to do experiments, learn from that and apply the know-how to production code.
misja111 4y ago
> Imagine a chef trying to come up with a new dish. I suspect they don't write it down first. Many chefs do. Especially when it's about the presentation on the plate, many chefs make a sketch first before they prepare the new dish for the first time.
- dgb23 4y ago
  Exactly! In my experience, a chef will do reasearch (they have a ton of notes/books/recipes), then combine some stuff and try things, but then will 100% write things down. Documentation is a key ingredient in cooking.
4y ago

allenu 4y ago

My opinion is this post romanticizes the idea of planning before building anything a little too much. As with anything, the devil is in the details. I agree that some type of high-level planning is needed before you do significant coding or design. However, just how much really depends on what you're building. I don't really buy into the notion that writing a lot first will get to the heart of what you want to build. There are far too many unknowns up front. You'll have to start prototyping and experimenting to really know if what you've planned has any merit in terms of a real product. What you've written will give you a map of where you're trying to go, but you'll need to be flexible enough to change some of those initial plans if reality doesn't match your expectations.

andi999 4y ago
UML left the room..
dgb23 4y ago
When you can’t write a functional spec of something, then exploration/prototyping is in order. But that doesn’t mean you shouldn’t write one when you can. It’s very useful to get people on literally the same page.

andmarios 4y ago

I think the word documentation is not used correctly in the article. The article seems to suggest small snippets of text, ranging from one short paragraph to a few pages. It also goes on to explain documentation as memo / press release / reference card. But all these are not documentation. It sounds like the PRFAQ method, which is already in use by many teams. It's good, especially because it aligns people across all verticals of a company.

self_awareness 4y ago

It's not about using the pen and paper before the build. It's about building prototypes before the actual product. There's nothing wrong with prototyping the software using code and building it directly. The problem is when the prototype is being automatically elevated to a product rank when it starts working. In such case, everyone treats the prototype as it were a product, but in reality it's still a prototype. So instead of using pen & paper, just use the code to prototype things, because it's 2022 and it's possible to do so. Just make sure to properly transform the prototype into a full-fledged product when the time comes, possibly by rewriting the implementation, maybe even change the implementation language (e.g. Python for prototyping, C++ for implementation).

brzezmac 4y ago

So we have come full circle. That's the way we have been building software when I was starting with professional software development (this was around 2005). But the idea of doing a thorough analysis (business, technical) is a little bit older. The only people to whom this might come as a surprise are the ones who've drank too much of the "agile Kool-aid". I'm not here to bash agile and start this flame war all over again (agile has it's merits ...), but somehow thinking before doing got a bad rap recently (for reasons beyond me). It's like software development got trapped inside of King Julian's (from Madagascar movies/series) brain with his modus operandi: "let's start doing this before we figure out it does not make any sense".

shreyshnaccount 4y ago
Because thinking clearly is the hard part. I use Github copilot every day for work (and it generates decent code completion for me) and the only thing I've realised is that the major work in programming is to think clearly, and converting thoughts to syntax is not really that hard. Copilot takes off that easier cognitive workload and helps me focus and clear my thoughts. Also, does anyone know how to think clearly or does that just come with practice and experience?
- brzezmac 4y ago
  Thinking, especially abstract thinking, is crucial to software development, as often (not always) creating software is abstracting real life into algorithms and data structures. Writing text in a word procesor, notepad, etc. is in my opinion first step to validation of the idea, to having at least faint idea about the complexity of the solution we would like to build. On the question of "how to think clearly" - I'd say it's pretty individual - some people start "from the bottom", some "from the top" and others "in the middle". Experience is to know which is which and which approach suits you best.
  - shreyshnaccount 4y ago
    Wise words. That's prolly why you need to be good at math to be good at tech, abstract thinking all the way

toolslive 4y ago

Actually, you can do both at the same time: write a functional spec that you can run to see if it's correct. https://www.researchgate.net/publication/2468505_Functional_Specification_of_JPEG_Decompression_and_an_Implementation_for_Free https://www.researchgate.net/publication/2468505_Functional_... The idea never caught on.

ubercore 4y ago
My first job out of college was working for someone that wanted to implement whole systems in XML documents and use XSLT transforms to turn them into working code and documentation at the same time. That approach didn't last very long. But hey at least I learned the Muenchian Method.
- toolslive 4y ago
  xml is not a programming language, haskell (actually Gofer) is. I guess that was part of the problem.
  - ubercore 4y ago
    There were a lot of problems...

dusted 4y ago

If I'm writing some small tool, I often start with fictional workflow examples.. These get adjusted as I discover ways that the implementation can be made simpler or easier without any significant changes to the workflow.. Other times I find that the workflow is annoying and that a larger complexity in the implementation is well worth it for a nicer workflow.. What I'm trying to convey is that it's often better to BOTH have a lose idea of how it should be used AND how to implement it, but be ready and able to change both implementation and workflow/documentation as new discoveries are made.. In the end, if you know the implementation AND workflow EXACTLY, it's because the program already exists and you should just use that instead..

bajsejohannes 4y ago

> Writing is a way of finding out Writing _code_ is also a way to find out.

jpswade 4y ago

I think "Working Backwards: Insights, Stories, and Secrets from Inside Amazon" by Bill Carr puts this better. Their idea is that you start with what the press release might be, something everyone can get excited about, and then work backwards from that.

singularity2001 4y ago

One problem for me is that I lose motivation after writing the documentation, thinking that burdensome implementation of the details should be left as an exercise to others.

dgb23 4y ago
That’s a dangerous notion, because you might be overestimating your ability to think things through in detail. It’s typical to revist a spec and iterate on it. Also a program literally is a specific spec for a given computing environment, and there are often many interesting things to figure out.

hazelnut-tree 4y ago

I like the documentation first approach, but I understand that it does not work for everyone. Designing a program (on paper or the screen) before you start coding is still the recommended textbook approach from university courses and books. I think of documentation in the broadest form. For example, flow diagrams, or rough wireframes of screens in your app. Figma (and other tools) is good for creating rough app prototypes with short annotations describing features. You get the benefit of fleshing out flows and screens or pages (before coding) but without heavy documentation. A popular UX technique you can try by yourself (or with colleagues) called 'Design The Box' can also be used before you start coding. It's an exercise to articulate the key features and benefits of your app: https://gamestorming.com/design-the-box/ https://gamestorming.com/design-the-box/

BiteCode_dev 4y ago

This advice works only if 5 prerequisites are met: - the coder is fluent in programming. Beginners will not know how to architecture things, and need to fiddle way more. It's impossible for them to create a doc that will make sense from the top of their head. - The coder understands the problem well, and it has a known solution. Many problems are better understood when trying to solve them, by exploring its space while programming. It's impossible to start documenting something you don't know very well. It's espacially true if you have to come up with a novel solution. - The problem is well defined. Unlikely. Clients don't define their problem well, and it's half our job to extract the information from their brain. However, while it is sometimes possible to get that on paper, and formalize it, most of the time, programming an incorrect PoC and iterating on it is a better interface to communicate with the client: they have a visual result to discuss. Writting a doc that you trash down every day would be a waste. - The coder understands the field well. I'm currently working with a Bank, and I don't know the field. Many algo I must implement are in the head of my clients, and the quickest road to understanding them is to peer code them. They attempted to make a formal doc first of course. After 6 months, they still don't agree on how to do some things. One week of coding with me forced them to confront reality, and take concrete decisions. - The coder has the big picture. Starting with a doc assumes you know what your API should look like. I would recommand that you do know, if you don't, you are probably in trouble. But it's a fact of life that sometimes you can't figure it out, and starting from something incomplete and coding it will make the big picture clearer. That's a lot of pre-conditions. My experience is that most teams starting with the doc (or tests) don't ship, or end up shipping only once they start fiddling. Those who do are excellent teams, the best ones, and I love working with them. But they are a rare bread. We are usually an average team, not ticking all pre-conditions, and not composed of only very skilled or experienced professionals. We fiddle a lot. And unless you have a great team leader, taking such an ordinarity team and making it write the doc first will result in a terrible doc that doesn't match the solution to the problem, that you will rework again and again, while nothing is getting in the hand of the client for concrete feedback. I favor a middle ground: start with paper, but don't pretend you are going to have a full spec.

somishere 4y ago

I mean yes, but also no way. I think the term 'documentation' (in a dev context anyway) is a daunting one. Documentation is hard. Time is poor. And things always change in build, often big things. Knowing the process, why would you presume the outcome? That said, even on personal projects I do like to write a readme.md (a scope of work "lite" - audience me) outlining the intention and key features of whatever it is I am planning to create. This isn't a massive commitment, neither detailed nor prescriptive, but it does provide a reasonable amount of guidance and milestones. But it's not documentation.

drunkenmagician 4y ago

Hmmm, I think it depends on how much documentation. Design docs are important to clarify and communicate the intent. But typically (at least in my personal experience), designs evolve during the implementation as better understanding and consideration of edge cases comes to light. I now personally favour light weight PoC projects for any non trivial development projects.

anotheraccount9 4y ago

Instead, some sort of visual documentation, showing the milestones and fundamentals of what is expected.

phforms 4y ago

I think the process highly depends on what you know about the requirements and what is unknown. More established and standardized fields like mechanical engineering already know a lot of things upfront and can specify/document what the project is supposed to implement without having to tinker and experiment first. That may also be true for some types of products in SE that have been built hundreds of times before or some types of problems that we already know how to solve. But with many other projects, a lot of uncertainty comes along, where we don’t even know what we don’t know yet. In these cases it can be a great waste of time and energy to try and fix design decisions upfront, based on a theory of how things supposedly will work. In my experience, a lot of important insights can only be generated while you operate with the matter at hand (or at least imagine doing so, but this is very hard and inaccurate in more complex cases). Therefore, I believe that doing small, isolated experiments/prototypes before writing any documentation (and certainly before writing production-level code) is a crucial first step that should not be avoided unless you have a very solid understanding of what you’re about to build. I agree, however, that we shouldn’t start coding for production before doing any sort of research and design step first (although I don’t think that it is a linear process – we might have to cycle through these stages repeatedly). I have worked in graphic design for many years before doing SE and my more challenging projects always needed multiple practical experiments – planning everything in my head upfront never got me anywhere. Of course, GD and SE cannot be compared 1:1, but both involve research and design. Of course, planning experiments can still be fruitful and it certainly helps to formulate scope and intent beforehand so you know what problems you are trying to solve (this is how I would see the role of the press release mentioned in the article). For more complex, long-term projects, I like to keep a dev journal where I can document my research and approaches while working on experiments and prototypes. This helps me a lot later on to re-trace my thinking process and the act of writing certainly helps to organize and focus my thoughts. I don’t think of this as a techical documentation/specification, but maybe it is one of the things the author of this article had in mind.

lakomen 4y ago

I don't know... When I start something new it's often spontaneous. I have this idea I'd like to try and then I start hacking. And while I hack at the keyboard and create the basis I think of the long term. Having to do double work, write a document first and then repeat the same in code is extremely counterproductive. Motivation plays a big role. Repetition is not fun. Most projects never get finished. There are always obstacles and some are really hard. But you won't know them from writing documentation alone. And if you write documentation ahead of time it's very likely this documentation will not fit the final product, at 1st release time. Having a general outline with key features is ok. But fully-fledged documentation is over the top. That's my educated opinion at least. Motivation is very important for me, especially if I don't know for years if this thing I'm building will be used by people at all. Single developer. If there were dedicated people for tasks, that'd be different, probably. Also you can't take the established business and say they all had a memo or document and that's the reason why they succeeded. That's a really long shot, IMHO.

tuxie_ 4y ago
I completely agree with your point here. As I wrote in a previous comment for a different post: I'm currently developing an "experimental" piece of software, i.e. I am not even sure some features I want to add are possible, meaning I had to rewrite it a couple of times (and won't be the last). Having strict versioning, pinning, and documenting everything before it reaches a semi-stable state would discourage me from developing it altogether.
geek_at 4y ago
So true, when I say in engineering school we had a subject called project management and we were taught that you have to write the documentation and everything first and it should be done in such a detail (including variable names and such) that you can give the project documentation to three different programmers and receive the exact same product from all three. I always hated this approach because of the reasons you stated. I love the quote from that German hacker Fefe: "Coding is an explorative process"
- quickthrower2 4y ago

ajani 4y ago

I tend to do the exact opposite. Only when the program is fully done (if ever) do I document it (beyond peppered lines of documentation that explain something that is not obvious from code). There is good reason for this: Premature abstraction. As others have pointed out when I start to work on an idea, I’m not sure about everything. Working on it will reveal misassumptions and blind spots in my current thinking. I have also learned to abstract out behavior into functions lazily. Often having created defined functions with an immaturely developed idea is a hindrance to flexible experimentation.

samsquire 4y ago

I must agree with this. I understand algorithms more after I write down what they actually mean or do and why. The implementation is secondary. I would rather read what an algorithm does than read your implementation. Even though the implementation is more useful from an execution perspective. From the description I can write my own. It's easier for me to understand a plain description of an algorithm or technology than the code that implements it. Reading code is an investment. Reading code is harder than reading English of the same..I understand that English is imprecise but from a detailed description of say the Chrome layout engine I could probably learn how to write a layout algorithm but the documentation for layout algorithms doesn't exist in a digestible form so you are forced to read Chromium sourcecode. The ORC whitepaper uses branch and bound optimisation technique paired with a constraint satisfaction optimiser. I suspect I can use ORTools. How many alternative rendering engines are there really? IMGUI, video game layout engines and video game engines, Gecko, Blink, WebKit and JavaFX and Swing and Qt QML

vintagedave 4y ago

Like some other commenters, I disagreed with the headline. But the article says something more subtle than 'write documentation first'. Its points are: * Write documentation alongside, ie as you go * Use writing English (or your language) documentation as a way to clarify your thoughts: the process of writing is a tool to ensure something is well thought through I disagreed with the headline because I interpreted it as writing end-user documentation, effectively a very detailed specification document, up-front and then writing code to match. In reality, coding is a process of discovery, and you need the flexibility to allow the implementation to change. Your goal might be known, but the path to that goal is flexible. The article pitches writing that goal upfront. Visicalc had a few sample formulae. Nest had a press release written. But for both, and it's explicitly called out for Visicalc, the actual user-facing documentation was written alongside the code as the product developed. This solves the problem of not having documentation ready when the product is ready, too. In short: misleading headline, insightful article. I'd like to take its suggestion of writing docs alongside implementation as implementation develops on board myself.

plaguepilled 4y ago

Yes yes yes a million times yes. I need this engraved into the skull of every tech lead that claims the code is the documentation. The engraving will be appropriately referenced. It will also link to another engraving that documentation is good actually.

leetrout 4y ago

I like this because I value alignment. Writing (and meetings) offer the chance to get aligned.

nawgz 4y ago
But how can writings and meetings align code that doesn't yet exist? Are you a believer that during writing of documentation, you can anticipate each code challenge and solve it ahead of time?
- leetrout 4y ago
  Alignment of humans. Their intents and expectations.

nottorp 4y ago

Someone rediscovering waterfall?

Simplicitas 4y ago

Good luck convincing management of that.

papito 4y ago

So one camp says "just jump in and code", the other one advises to go full waterfall and write books of documentation. Yet again, the new generation is making the same mistakes us fossils learned from years ago. You will be shocked to find out that the truth is in the middle. "Jumping in an hacking" is a recipe for a waste of life (but seems fine when you are young and the time seems eternal). Yes, you will eventually get it done, but after going down rabbit holes and "just getting it to work", you will end up with code that, let's just say, down the road you will not be proud of. Trying to think everything through in advance is a fool's errand. Your "documentation" will be useless after you write the first few lines of code, unless you are clairvoyant and can predict every little problem. Think before you write, that's all. Think more, write less. I spend more time thinking about what I am about to write, but at some point I have to start coding, before I enter the analysis paralysis stage.

_gabe_ 4y ago

> So when Bezos—in a possibly apocryphally, 128-word memo—wrote that “All teams will henceforth expose their data and functionality through service interfaces,” it was a focused idea that led to Amazon building web services for which it’d be it’s own best customer, and turned AWS into the cloud computing juggernaut it is today. Last I checked, almost every AWS api has a V2. And wait, I just checked, AWS CDK is on V2.28.0. I wonder why the last 28 versions of V2 didn't work if they wrote the documentation first? Last I checked, Mac OS is on like version 11 or something? I'm not a Mac user so I don't follow this stuff. Clearly, documentation is not a silver bullet. If it was, we wouldn't have to continue to rewrite and bump the versions of all of our tools. When I worked at Amazon, writing that 6 page document was like agonizing torture. They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that?? I don't know what other APIs I may or may not have to call to actually get this to work. Implementation details matter a lot. I don't remember who said this, but there's a saying that's something like ideas are worth nothing. Execution is worth everything. And the same thing goes for documentation, what good is documentation without a final product? It's useless.

sumy23 4y ago
> They would ask me what the minimal latency of the API I was creating would be, and how am I supposed to know that? Isn’t that part of the job? When writing a technical document, you need to research things like dependencies, data storage, caching and estimate expected latency.
- _gabe_ 4y ago
  The only way to get an accurate estimate of expected latency is to measure it in all sorts of different scenarios. You can't measure something that doesn't exist. And relying on other peoples documentation for accurate latency estimates is asking for trouble. The one thing I've learned through profiling a lot of my code is that my intuitions about how long something will take are always wrong.
  - sumy23 4y ago

rubyist5eva 4y ago

As someone who just got promoted into engineering management from development, the number one cause of frustration, delays, confusion was always lack of documentation - either in requirements or just how the system works in general. It’s now my number one priority to ensure that we have a proper framework for documenting requirements ie. no more two-line “change this functionality because reasons” tickets and having a centralized wiki that documents all features and how the work, along with any quirks that exist.

rmbyrro 4y ago

This is good advice especially for developer tools. Start with the API interface first: 1. Ask what problems the tool intends to solve 2. Then ask what's the best experience for developers to command or program it "Best experience" depends on the context. A few factors worth consideration are: - Succinctness - Easiness to understand - Memorability - Clarity - Familiarity (if developers are already used to some existent API) Then build whatever is needed to make that API get developers from point A to point B.

bitwize 4y ago

I find that the quality of my output tends to increase if I'm Literate Programming. And in that regard, documentation is like testing: whether you do it first or second doesn't matter as long as you do it and integrate it into your process. I tend to find that I'm chasing an idea and hacking code together without updating the docs. Then I hit a complexity wall and go back and look at the big ball of mud I made, and break it into pieces, updating the documentation for each piece, and then I get a refactor idea that helps me simplify the code.

pete_nic 4y ago

I feel like a more appropriate name would be “write first, then build”. “Documentation” reminds the product managers and engineers of corporate-y documents like release notes. The “documentation” described is more of a fluid collection of ideas than what we would consider “documentation”. I have found this to be true - “Writing is a way of finding out”.

linsomniac 4y ago

"The sooner you start to code, the longer the program will take."

marcosdumay 4y ago
Just like "two programmers can always achieve in two months what takes an entire month for a single programmer", the one we imported from sciences "a short week programming can save you many hours of thinking", and other similar famous phrases, this is true when it is; when it isn't, it's false.

zugi 4y ago

Aren't we supposed to write unit tests before we build too? The benefit of that is that if you have a CI system the tests have to stay current with the code. Whereas documentation quckly gets out of sync with the actual code.

boredumb 4y ago

If you're best at designing and building front ends, go build that first and plug into an API later. If you're best at writing backend code and APIs, go build that first and plug in your front end later. If you're best at writing docs and speccing, go build that first and then iterate through the two items above.

stefanve 4y ago

I can't remember the last time I worked somewhere where nobody wrote down anything. Sure sometimes not enough and sometimes too much. But in general people write down specs in, stories, tasks, pitches, presentations, wireframe, slick UIs etc. Even for my own play projects I generally start out with an outline of some sorts. but total spec upfront brings back bad memories from the waterfall world. But I have also had discussions with folks who thought that agile means not specs/documentation at all

voidhorse 4y ago

Tangential to the article but I’m curious to see what the app looks like once it releases. I’ve been thinking a lot recently about how software for editing text (not authoring) is woefully unexplored. When it comes to other mediums like video, software has maintained the film/edit division—one captures video with a camera then uses dedicated software to edit it. It remains a two-step process and the division between steps is reinforced by the design of supporting software. With writing, the opposite has happened. Software helped collapse the two-step divide between writing and editing. Text editors serve a dual purpose in that one can both produce the initial content and edit it thereafter all at once and seamlessly, in one tool, in one session. However, I remain convinced this is a bad way to do it and the two-step approach is the correct one. It’d be interesting to see what a tool dedicated only to the editing phase could look like (so, you can alter existing text but cannot use it to produce novel material).

bradrn 4y ago
> It’d be interesting to see what a tool dedicated only to the editing phase could look like (so, you can alter existing text but cannot use it to produce novel material). Scribus [https://www.scribus.net/ https://www.scribus.net/] specifically states that it’s meant for editing already-written text; I’d imagine that other publishing software (e.g. InDesign) works fairly similarly.

beshur 4y ago

My grandpa worked like this on a naval propulsion factory :) They had quite a long development lifecycle - decades for every new engine from inception to series production.

ChrisMarshallNY 4y ago

I've had a great deal of experience with the "Measure Twice, Cut Once" approach. Most of my career was at hardware companies, and hardware development tends to be about as Waterfall as you can get. It was incredibly frustrating, because they insisted that software be developed the same way as hardware. Efforts to tell them that software is different were met with sneers, and accusations of being "lazy," or "sloppy." The OP was done by a professional writer, so it's not surprising they have a "documentation-first" approach. I tend to use an approach I call "Forensic Design Documentation"[0], and "Evolutionary Design"[1]. Knowing what you want is not easy. That's the single biggest problem with a "requirements-first" approach. I've learned the value of rapid prototyping, and getting involvement from non-tech stakeholders, as early as possible, so the project design is iterative, and hands-on. But there was this chap named Damocles, and his sword is often brought up, in situations like this... "Rapid prototyping" is often taken as license to do sloppy work. The single biggest issue with rapid prototyping, is that management always assumes that the project is "done," and cut the schedule and budget, forcing you to use the junk prototype as the ship product. After a couple of these, I learned to make my prototypes top-quality, if functionally incomplete. That way, by the time management says "f**k it, let's ship!", the project is actually shipshape. And I am careful about documentation. I tend to use a lot of embedded documentation (headerdoc-style)[2]. That's because it "ages" well, and tends to be a lot less of a "concrete galosh."[3] [0] https://littlegreenviper.com/miscellany/forensic-design-documentation/ https://littlegreenviper.com/miscellany/forensic-design-docu... [1] https://littlegreenviper.com/miscellany/evolutionary-design-specification/ https://littlegreenviper.com/miscellany/evolutionary-design-... [2] https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ [3] https://littlegreenviper.com/miscellany/concrete-galoshes/ https://littlegreenviper.com/miscellany/concrete-galoshes/

jstimpfle 4y ago
How do you make prototypes top-quality? Unless you know what you want, isn't it hard to make the best shape for that thing?
- ChrisMarshallNY 4y ago

productceo 4y ago

Always the right approach and only the right approach

hoosieree 4y ago

For work projects, I often write a short README file first, and share it with my team as a sanity check before writing a single line of code. It's just rough draft which says "here is the problem I think we are solving, and why/how we're solving it". If my team has feedback, I update the README. This is easier to keep track of than Slack conversations. If necessary, this document can be polished later, when other people need to use the thing we built. But it's nice to have a starting point.

bern4444 4y ago

A company I was at followed this approach. But of course putting it in writing then meant it had to be shared and approved or "reviewed"(reviewers of course thought they were approvers which was never the case). We called them TDDs (Technical Design Documents) and they were a nightmare. The docs were often out of date, as the actual engineering would deviate strongly over time (and short periods of time too, like days). They were incomplete as we wouldn't quite know what was involved until we actually began figuring it out by writing code and building POCs. We also wouldn't know how far we'd want to take some decisions until we had code to then figure out questions about share-ability, extensibility, ownership, etc. The project would take significantly longer as everyone would first work on the TDD before ever working with code. Then you'd have to corral approvals which involved comments, questions, and a lot of back and forth. This would take days and could stretch out into weeks. All in all it became a PITA and I wouldn't care to ever continue this practice. I agree writing helps clarify intent and understanding, for software that writing comes through by writing code. Phrases like measure twice and cut once don't really make sense for software where getting new wood to cut has an effective marginal cost of 0. Software is completely different from any physical good so these analogies just don't make sense. It's not like a building where once it's built it's impossible or difficult to change. We can forever update, improve, repurpose, and clean up any and all aspects. Write a README or a TDD once the project is done to capture how it works, the problem being solved, or any gotchas, limitations, or ideas for future development. But this should go at the end. Lean in to software's strength of exceptional flexibility and adaptibility and stop treating it like a physical thing.

atx42 4y ago

Always upvote articles that imply Agile can be lacking. Really, meta-processes are the way to go, and can be defined by checklists. E.g. For this effort, will documentation be helpful? check yes/no. Then you aren't blindly just doing stuff because it is or is not part of the process. The process itself is configurable.

JonChesterfield 4y ago

Build first. Then write down what you should have built. Then build that thing second. All documentation first wins you is documentation to throw away along with the first revision.

b3morales 4y ago
You can (should) extend this forward too! Build a mockup, write a doc describing that, then write a rough implementation, revise, and so on.

SenHeng 4y ago

I just happened to be reading up on Readme Driven Development[0] last night and the HN thread[1] had a few mentions of Donald Knuth's Literate Programming[2]. Fascinating read. [0]: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve... [1]: https://news.ycombinator.com/item?id=17427593 https://news.ycombinator.com/item?id=17427593 [2]: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming

spurgu 4y ago

A lot of good ideas come through trial and error. After a certain while of using a product a specific way whole new pathways can open up. It's really difficult to know what your end product is supposed to look like, if you're working on something novel. If you're building something that already exists, sure, then you can structure and optimize it during the design phase (and should).

mihaigalos 4y ago

I see tests as executable documentation/specification. TDD reinforces that view. i.e. rust even has the specification of parts of its functionality using asserts (in the docs): https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#examples https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#exa...

lr1970 4y ago

IMHO, the process of software project development is iterative and non-linear. Writing some docs followed by some code, then writing/editing more docs, then more code, tests, experiments ... rinse and repeat. I found that any rigid structure like docs-before-code or code-before-docs to be counterproductive.

AtlasBarfed 4y ago

This is worse than TDD "write the test first" extremism. The # of projects that have all the requirements perfectly laid out to enable this is... effectively zero. I can see something where the requirements and iteration/convergence artifacts lead to some structured documentation ... maybe, that's an interesting idea. The reason documentation comes last is that you don't know what comes out the end of the sewer pipe after the vagaries of Faster, Better, Cheaper pick two... well actually it's Faster Better Cheaper Documented ProcessFollowed, pick 2.5.

elesbao 4y ago

I like the idea of at least writing a PR and FAQ (where a build is a product). That helps a lot fo manage anxiety and kill backlogs.

charliepark 4y ago

Small correction: you mention the Apple documentation specialist Jef Raskin, but you spelled his name with two “f”s; his name only had one.

pipeline_peak 4y ago

Cobble together stackoverflow code, don’t write docs, instead hire entry level devs to fix the cryptic levels of technical debt in your code, reward them with seniority for how long they endured.

main3523 4y ago