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.
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.
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.
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.
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.
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.
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 :)
> Out of date docs are often harmful and demoralizing because they break trust.
I agree, however the flipside failure mode is the initial rough design checks the "design doc" box and is never updated, so it remains vague and/or inaccurate.
Any process ultimately is only as strong as the people following it.
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.
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.
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."
It’s definitely possible I got the order wrong. I still feel reasonably confident that documentation, and the general ideas sketched out on the VisiCalc reference card, were a core part of the start of the project, before the code was anywhere near finalized. I’m trying to find an update if I’m able to, but there was a copy I saw in my research of the VisiCalc reference card made before the program was finished, with a sketch instead of a screenshot, and then it showed what changed and what didn’t between that and the release. And Frankston comment about that if the code couldn’t match the card, they’d change the code, seemed to me that at least the docs set the tone for the code, and not the other way around.
Fadell’s writing the press release before building the Nest and Raskin writing The Book of Macintosh to kick off the original Mac, though, both are directly documented so we can be certain there.
At any rate, appreciate the push back—definitely want to have the story straight! Will dig a bit more on VisiCalc and see if I can find more confirmation.
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.
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)
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.
Software Engineering is still in the stage of early industrialism - when James Watt built his steam engine, or Carl Benz built his car, they did not have specification documents. They tinkered and made it work, moving around assemblies until everything fit, then improved on the design. Essentially, they were doing some form of 'agile': small teams (to the point of only one), no specifications, high turnover. Today, this approach is unthinkable in mechanical engineering, because bad designs are lethal.
The software engineering environment is special because when it started out, everyone thought of it as just another branch of engineering, so they applied standard industrial processes onto it - and that did not work well, what worked for building hydraulic presses did not translate well to writing software. SE needed to "learn" how to tinker and experiment on mid-sized projects first, and now they are in an early-industrial-age phase (and call it 'agile').
Eventually, SE will return to something more organized, something more reliable - after all, we are learning that bad design choices can be lethal. We are seeing the first steps today, trying to capture agility with frameworks, with dedicated test methodologies, ... Naturally, this will cause frustration with the tinkerers, and it will take time. And while some aspects will resemble mechanical engineering processes, some things will be completely new and untranslatable to other engineering disciplines.
We've been waiting for years for software to become something more organized and reliable. It will take a rethinking of the fundamentals to get there IMO, along the lines of Brad Cox's thinking in [0]. Object-oriented programming was a revelation for a period, but overhype and overselling has made it non grata to a lot of developers. Now we wonder, what the next iteration of progress will be?
Is this even true? Applying engineering project management and methodology to software was the default approach historically. This is essentially the waterfall/BDUF that "agile" was reacting to.
The OP is just content marketing for some proofreading software. No one actually thinks this stuff is an epiphany unless they are completely unfamiliar with the history of the field.
With hardware (be it a bridge, a car, a pair of jeans) customers know and accept that no modification is possible once the product is accepted. With software, customers have grown acquainted to the reality that software will evolve to fit their changing needs. Later, this became hoping for a software that can anticipate their needs. Finally, it perversely morphed into expecting a software that precede them being aware of their own needs.
Documentation (and press releases/FAQs) are usually for users. Specifications are for developers. The former can precede and help with forming the latter.
> So, in other words: write a specification document and then build.
I don't believe this is what the article is saying at all. I interpreted the headline that way, but the article seems to be saying to hav a goal upfront (written) and write docs along the way, also using the process of writing text as a way to clarify thinking.
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.
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.
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) 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.
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.
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.
"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.
> 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.
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.
I think that's the key point being lost in any of these over-generalizations of "software" separated from actual industries and customer types.
Building a back-end system for a corporate client? Yeah, probably write a spec first and get them to sign off.
Starting an API-driven business, selling metered REST API resources? Definitely a strong case for writing the docs first, which are key to adoption and usage.
Building a new social, dating, or media network? Seems unlikely the docs are going to be a deciding factor in those projects' success.
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.
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.
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.
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).
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".
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?
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.
>somehow thinking before doing got a bad rap recently (for reasons beyond me).
I've seen plenty of software devs engage in detailed forward planning for a future that would be utterly different from what they expected.
Best case this rendered all that forward planning moot and a waste of time. Medium case is they did a lot of pointless work. Worst case they technologically straitjacketed themselves and dug multiple holes they couldnt extricate themselves from easily.
Then they'd pick themselves up and do it all over again thinking that if they (or more usually somebody else) just managed to predict the future better then this kind of shit wouldnt happen. E.g. those idiot PMs just need to provide better requirements.
It's a hard rut to get out of because in so many other spheres of life forward upfront planning is critical and the future IS predictable. Software intuitively feels like it should be too. But it's the exact fucking opposite of that.
This is, at least, why certain kinds of thinking before doing got a bad rap with me.
Sounds like a problem with the execution instead of the technique.
The alternative to thinking before doing is wandering aimlessly, which really isn't likely to steer you where you want to be.
We basically developed whole-ass treatises (and some unhealthy cargo cults) around people saying that the observe -> think -> do -> restart loop should be small and leave space for adjustments between each step.
> The alternative to thinking before doing is wandering aimlessly, which really isn't likely to steer you where you want to be.
When I was a kid, we topped over this hill on the interstate, and way down in the distance there was an overpass across the road, with straight road from here to there. And I wondered how my dad could aim the car so well that it would go under that overpass way off in the distance.
Of course, now I know that he didn't do that. He didn't even try to do that. Instead, he steered the car.
The alternative to thinking before doing is not wandering aimlessly. It's steering. It's knowing where you're trying to go, even if you don't exactly know how to get there, and having an initial idea of how to get there, and then starting to go there, and adjusting as you find obstacles that you didn't know existed, and as you find that your aim was off.
Agile and Documentation-Driven-Development can not only easily go hand in hand, I think agile is perfectly suited to work like this.
We figure out what the software is supposed to do -> We write documentation describing that -> We build the implementation -> New Requirements -> Figure out how to incorporate them into the plan -> Update the documentation -> Build the changes.
It's an iterative process, perfectly suited to agile development.
I would assume that an agile process will rely on Markdown, but then it some point does it get (irreversibly) committed to a more conventional document format.
If assume (please correct me if I'm wrong) by "conventional document format" you mean ones that do not play well with version control software like git (eg. because they may be/contain huge binary blobs), yes?
If so, at least in the projects I am involved in, all documentation that is checked into the repos remains in markdown (asciidoc is also used alot), and is only converted to non-plaintext formats for the purposes of release.
This is similar to how we build executables from our source code, but don't check in the resulting binary files into the repo.
Yes, by "conventional document format" I meant something in the Microsoft crapiverse.
Keeping it in markdown/asciidoc sounds great if you can make it work. Is your work in technical environments ? Where people have no expectation of using MS Word ? And those users that need fancy features like footnotes can learn how to use them and then retain that knowledge and use the features without inadvertantly document damage ?
I ask because I worked TC in a software firm targeting Microsoft platforms, so they relied on Word (and Sharepoint), and were resistant to ideas of XML and structured documentation, and Markdown never even raised its head.
The phrase I hang on to is something thrown out by someone I used to work with - "Agile isn't an excuse not to do things". Too many organisation use "we're doing Agile" as an excuse not to do any design thinking and instead "just code".
What Agile actually is (in the most general terms) is a different order of doing things that increases the amount of knowledge you have when you do it, and reduces the chances of wasting your work. In my example, you still do the design work, but rather than doing it for the whole system at once you do it for the piece you're about to do, and then implement that piece[1].
But yes, it's nice that the internet has discovered Waterfall!
[1] Although many systems, even in an agile world, do require a degree of up front "whole system" architecture and/or design thinking.
I think you can sum it up this way: be planning heavy where it makes sense, and agile where it makes sense. There is not true one way. I'd not want to use agile to develop the formula language in a spreadsheet, and I'd not want to waterfall a marketing website for a product that is speculative. Common sense applies.
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.
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..
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.
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.
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/
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.
158 comments
[ 3.0 ms ] story [ 209 ms ] threadIf 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.
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.
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.
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.
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.
However, as always YMMV and you might not get the luxury of re-writing :)
I agree, however the flipside failure mode is the initial rough design checks the "design doc" box and is never updated, so it remains vague and/or inaccurate.
Any process ultimately is only as strong as the people following it.
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/implementingvisica...
[2] https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest...
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.
>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."
Fadell’s writing the press release before building the Nest and Raskin writing The Book of Macintosh to kick off the original Mac, though, both are directly documented so we can be certain there.
At any rate, appreciate the push back—definitely want to have the story straight! Will dig a bit more on VisiCalc and see if I can find more confirmation.
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.
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.
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.
I love how the most basic of practices in any engineering field is depicted as a groundbreaking epiphany in the software industry.
The software engineering environment is special because when it started out, everyone thought of it as just another branch of engineering, so they applied standard industrial processes onto it - and that did not work well, what worked for building hydraulic presses did not translate well to writing software. SE needed to "learn" how to tinker and experiment on mid-sized projects first, and now they are in an early-industrial-age phase (and call it 'agile').
Eventually, SE will return to something more organized, something more reliable - after all, we are learning that bad design choices can be lethal. We are seeing the first steps today, trying to capture agility with frameworks, with dedicated test methodologies, ... Naturally, this will cause frustration with the tinkerers, and it will take time. And while some aspects will resemble mechanical engineering processes, some things will be completely new and untranslatable to other engineering disciplines.
[0] https://www.researchgate.net/profile/Brad-Cox-2/publication/...
The OP is just content marketing for some proofreading software. No one actually thinks this stuff is an epiphany unless they are completely unfamiliar with the history of the field.
With hardware (be it a bridge, a car, a pair of jeans) customers know and accept that no modification is possible once the product is accepted. With software, customers have grown acquainted to the reality that software will evolve to fit their changing needs. Later, this became hoping for a software that can anticipate their needs. Finally, it perversely morphed into expecting a software that precede them being aware of their own needs.
I don't believe this is what the article is saying at all. I interpreted the headline that way, but the article seems to be saying to hav a goal upfront (written) and write docs along the way, also using the process of writing text as a way to clarify thinking.
See comment: https://news.ycombinator.com/item?id=31751399
Some might take exception to that.
As usual, some times this is a good choice. Even more if you choose a good iteration size.
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) 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.
Quite often when drafting a question to a problem I'm facing, halfway through I'll discover the flaw in my reasoning or code.
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.
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.
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.
Documentation is a key ingredient in cooking.
I think that's the key point being lost in any of these over-generalizations of "software" separated from actual industries and customer types.
Building a back-end system for a corporate client? Yeah, probably write a spec first and get them to sign off.
Starting an API-driven business, selling metered REST API resources? Definitely a strong case for writing the docs first, which are key to adoption and usage.
Building a new social, dating, or media network? Seems unlikely the docs are going to be a deciding factor in those projects' success.
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.
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.
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).
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".
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.
I've seen plenty of software devs engage in detailed forward planning for a future that would be utterly different from what they expected.
Best case this rendered all that forward planning moot and a waste of time. Medium case is they did a lot of pointless work. Worst case they technologically straitjacketed themselves and dug multiple holes they couldnt extricate themselves from easily.
Then they'd pick themselves up and do it all over again thinking that if they (or more usually somebody else) just managed to predict the future better then this kind of shit wouldnt happen. E.g. those idiot PMs just need to provide better requirements.
It's a hard rut to get out of because in so many other spheres of life forward upfront planning is critical and the future IS predictable. Software intuitively feels like it should be too. But it's the exact fucking opposite of that.
This is, at least, why certain kinds of thinking before doing got a bad rap with me.
The alternative to thinking before doing is wandering aimlessly, which really isn't likely to steer you where you want to be.
We basically developed whole-ass treatises (and some unhealthy cargo cults) around people saying that the observe -> think -> do -> restart loop should be small and leave space for adjustments between each step.
When I was a kid, we topped over this hill on the interstate, and way down in the distance there was an overpass across the road, with straight road from here to there. And I wondered how my dad could aim the car so well that it would go under that overpass way off in the distance.
Of course, now I know that he didn't do that. He didn't even try to do that. Instead, he steered the car.
The alternative to thinking before doing is not wandering aimlessly. It's steering. It's knowing where you're trying to go, even if you don't exactly know how to get there, and having an initial idea of how to get there, and then starting to go there, and adjusting as you find obstacles that you didn't know existed, and as you find that your aim was off.
We figure out what the software is supposed to do -> We write documentation describing that -> We build the implementation -> New Requirements -> Figure out how to incorporate them into the plan -> Update the documentation -> Build the changes.
It's an iterative process, perfectly suited to agile development.
If so, at least in the projects I am involved in, all documentation that is checked into the repos remains in markdown (asciidoc is also used alot), and is only converted to non-plaintext formats for the purposes of release.
This is similar to how we build executables from our source code, but don't check in the resulting binary files into the repo.
Keeping it in markdown/asciidoc sounds great if you can make it work. Is your work in technical environments ? Where people have no expectation of using MS Word ? And those users that need fancy features like footnotes can learn how to use them and then retain that knowledge and use the features without inadvertantly document damage ?
I ask because I worked TC in a software firm targeting Microsoft platforms, so they relied on Word (and Sharepoint), and were resistant to ideas of XML and structured documentation, and Markdown never even raised its head.
What Agile actually is (in the most general terms) is a different order of doing things that increases the amount of knowledge you have when you do it, and reduces the chances of wasting your work. In my example, you still do the design work, but rather than doing it for the whole system at once you do it for the piece you're about to do, and then implement that piece[1].
But yes, it's nice that the internet has discovered Waterfall!
[1] Although many systems, even in an agile world, do require a degree of up front "whole system" architecture and/or design thinking.
https://www.researchgate.net/publication/2468505_Functional_...
The idea never caught on.
That approach didn't last very long. But hey at least I learned the Muenchian Method.
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..
Writing _code_ is also a way to find out.
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.
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/
- 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.