Write documentation first, then build

219 点作者 maguay将近 3 年前

61 条评论

lakomen将近 3 年前

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.

评论 #31751705 未加载

评论 #31751081 未加载

评论 #31752296 未加载

评论 #31753000 未加载

评论 #31756775 未加载

评论 #31751561 未加载

评论 #31755245 未加载

评论 #31751448 未加载

评论 #31757832 未加载

评论 #31752866 未加载

drewcoo将近 3 年前

> 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] <a href="https://landley.net/history/mirror/apple2/implementingvisicalc.html" rel="nofollow">https://landley.net/history/mirror/apple2/implementingvisica...</a>[2] <a href="https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest-learning-thermostat" rel="nofollow">https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest...</a>

评论 #31749337 未加载

brzezmac将近 3 年前

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".

评论 #31753151 未加载

评论 #31750321 未加载

评论 #31753533 未加载

评论 #31751020 未加载

评论 #31750796 未加载

daenz将近 3 年前

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.

评论 #31749394 未加载

评论 #31749751 未加载

评论 #31749818 未加载

评论 #31755124 未加载

DigitalSea将近 3 年前

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.

评论 #31749582 未加载

评论 #31749277 未加载

评论 #31751632 未加载

评论 #31750827 未加载

评论 #31750849 未加载

_gabe_将近 3 年前

> 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.

评论 #31752650 未加载

评论 #31752590 未加载

评论 #31752345 未加载

评论 #31753242 未加载

greggman3将近 3 年前

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.

评论 #31749759 未加载

评论 #31750409 未加载

评论 #31753472 未加载

allenu将近 3 年前

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.

评论 #31750728 未加载

评论 #31749829 未加载

warning26将近 3 年前

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.

评论 #31749353 未加载

评论 #31749317 未加载

评论 #31750416 未加载

alin23将近 3 年前

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 (<a href="https://lunar.fyi" rel="nofollow">https://lunar.fyi</a>) 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.

samsquire将近 3 年前

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

toolslive将近 3 年前

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

评论 #31750638 未加载

oidar将近 3 年前

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

SenHeng将近 3 年前

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]: <a href="https://tom.preston-werner.com/2010/08/23/readme-driven-development.html" rel="nofollow">https://tom.preston-werner.com/2010/08/23/readme-driven-deve...</a>[1]: <a href="https://news.ycombinator.com/item?id=17427593" rel="nofollow">https://news.ycombinator.com/item?id=17427593</a>[2]: <a href="https://en.wikipedia.org/wiki/Literate_programming" rel="nofollow">https://en.wikipedia.org/wiki/Literate_programming</a>

captn3m0将近 3 年前

<a href="https://tom.preston-werner.com/2010/08/23/readme-driven-development.html" rel="nofollow">https://tom.preston-werner.com/2010/08/23/readme-driven-deve...</a>

aaronwalker将近 3 年前

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.

评论 #31749719 未加载

papito将近 3 年前

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.

bern4444将近 3 年前

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.

egithinji将近 3 年前

>“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.

LudwigNagasena将近 3 年前

Isn’t documentation written before building… just specification?

评论 #31756342 未加载

phforms将近 3 年前

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.

vintagedave将近 3 年前

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 throughI 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.

andmarios将近 3 年前

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.

spurgu将近 3 年前

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).

drunkenmagician将近 3 年前

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.

voidhorse将近 3 年前

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).

评论 #31752762 未加载

rmbyrro将近 3 年前

This is good advice especially for developer tools.Start with the API interface first:1. Ask what problems the tool intends to solve2. 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.

atx42将近 3 年前

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.

hazelnut-tree将近 3 年前

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: <a href="https://gamestorming.com/design-the-box/" rel="nofollow">https://gamestorming.com/design-the-box/</a>

boredumb将近 3 年前

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.

self_awareness将近 3 年前

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).

dusted将近 3 年前

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..

ajani将近 3 年前

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.

somishere将近 3 年前

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.

bitwize将近 3 年前

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.

AtlasBarfed将近 3 年前

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.

rubyist5eva将近 3 年前

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.

stefanve将近 3 年前

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

hoosieree将近 3 年前

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.

JonChesterfield将近 3 年前

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.

评论 #31755149 未加载

bajsejohannes将近 3 年前

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

mihaigalos将近 3 年前

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):<a href="https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#examples" rel="nofollow">https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#exa...</a>

pete_nic将近 3 年前

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”.

BiteCode_dev将近 3 年前

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.

lr1970将近 3 年前

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.

jpswade将近 3 年前

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.

farmin将近 3 年前

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.

zugi将近 3 年前

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.

pipeline_peak将近 3 年前

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.

plaguepilled将近 3 年前

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.

beshur将近 3 年前

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.

singularity2001将近 3 年前

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.

评论 #31750792 未加载

ChrisMarshallNY将近 3 年前

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] <a href="https://littlegreenviper.com/miscellany/forensic-design-documentation/" rel="nofollow">https://littlegreenviper.com/miscellany/forensic-design-docu...</a>[1] <a href="https://littlegreenviper.com/miscellany/evolutionary-design-specification/" rel="nofollow">https://littlegreenviper.com/miscellany/evolutionary-design-...</a>[2] <a href="https://littlegreenviper.com/miscellany/leaving-a-legacy/" rel="nofollow">https://littlegreenviper.com/miscellany/leaving-a-legacy/</a>[3] <a href="https://littlegreenviper.com/miscellany/concrete-galoshes/" rel="nofollow">https://littlegreenviper.com/miscellany/concrete-galoshes/</a>

评论 #31758739 未加载

charliepark将近 3 年前

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

elesbao将近 3 年前

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.

anotheraccount9将近 3 年前

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

leetrout将近 3 年前

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

评论 #31751651 未加载

linsomniac将近 3 年前

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

评论 #31756582 未加载

productceo将近 3 年前

Always the right approach and only the right approach

Simplicitas将近 3 年前

Good luck convincing management of that.

nottorp将近 3 年前

Someone rediscovering waterfall?