Comment by mr-wendel | Hacker News Reader

Comment by mr-wendel | Hacker News Reader

Stuff I'd add that I think is crucial, and all related to one topic: good writing!

1. Learn to write specs

Call it an RFC, call it a PRD, call it whatever. Writing out a plan for any project taking around a week or more is always worth it. Use it to establish scope and priorities. Keep a "Questions" section that you whittle away at as you seek out feedback. Make the body a hierarchy of design tasks and implementation ideas. Track revision history and keep it up-to-date.

You now have a great way to get sign-off from peers + management, an execution plan, a task breakdown for ticket management and historical documentation on what happened and why.

2. Be terse

Is that email looking a little long? Write a "TL;DR:" section at the top and then see what you can delete. If it's nothing, leave the "TL;DR:". Otherwise you may find you've included a lot of intermediate thinking and people only need to know the conclusions.

3. When learning something new, keep a dedicated list of "this looks like magic!" items

Use your "down time" to research items on this list instead of refreshing your favorite news aggregator. Ask your peers and mentors about them. Notice when tangental issues come up and spend a few extra minutes seeing how they're related and how that might yield some easier answers.

4. When you want to ask for help... defer clicking "send"

Whether its an IM or email, write it up on the side first. Start with your question and follow-up with what you've already done to walk through finding the answer to save the person the effort of starting from step one or pointing out the obvious thing you overlooked. Often this will lead you to answering your own question. If not, still wait 15-30 minutes (if you can) before sending it and work on something else. In that time you're likely to think of something you overlooked and avoid interrupting anyone.

> When learning something new, keep a dedicated list of "this looks like magic!" items. Use your "down time" to research items on this list instead of refreshing your favorite news aggregator.

Brilliant advice. It's also applicable to other areas of life, not just programming.

Do you happen to know of a properly written (publicly available) spec? I'd love to see a good example.

I've always found the OAuth 2.0 spec [0] to be well written.

[0] https://tools.ietf.org/html/rfc6749

I'm afraid not. The best I can do right now is offer an example outline of what I do. That said, if I'm working with a good project manager my format will differ: I'll focus a lot more on the technical details and leave all organizational aspects out (e.g. timelines, dependencies and impact on other teams, etc).

The key principle is that anyone (sales, marketing, support, product, etc) should be able to benefit from reading it and find it intuitive to see where you're getting into the technical details and skip ahead to the next major point.

1. Overview

A paragraph of two explaining the what and why of the project. Maybe some links to other related key documentation. Don't put anything technical here.

2. Change Log

Bullet-point list of dates and major changes. Think of it like a git commit history.

3. Scope

What systems are affected? Are there phases to the project to be called out? If its principally one system/repo/etc in question, what major components are changing?

4. Requirements/Tasks (the main body)

Use a numbered list and aggressively refactor as you go so high-level items rise to the "left" and all related details are broken out as sub-lists. You can loosely think of it as something like "[section] > [epic] > [task], [task], [task]". Prioritize the list based on dependencies so you're always referring back to already-mentioned requirements instead of yet-to-be defined things.

5. Supporting Docs

Put long-form examples, scenarios, diagrams, etc in their own section. Some people will only care about these, especially if they provide integration examples.

6. Concerns and Questions

Ideally by the time a first draft is done this section no longer exists, but usually you'll find that you need to do research or get feedback from others to finalize the whole thing.

Thank you! this is helpful

I would also add use version numbering on all docs and properly minute meetings and action points.

The operation manual of the original IBM PC from 1981 is a very good example.

Personal plug: I wrote an article about writing specs a while back. I use the IBM PC spec as an example, so you might find my article useful.

https://iskender.ee/2020/06/18/EE-Specs.html

"What even is a good specification, or the Huaqiangbei test"

Those three points are pure gold!

I'd also add that you don't need to be working on a major project to benefit from standing back to writing it out first. Much of what I write is just a few pages, but it's still useful. It saves time overall, helps others get up-to-speed fast, and is fun!

Not sure this is exactly what the commenter had in mind, but I think of Clojure's "design rationale" documents as good examples of thinking through a problem before executing. This is one for the language itself, but there are loads of others out there for other sub-projects.

https://clojure.org/about/rationale

> Do you happen to know of a properly written (publicly available) spec? I'd love to see a good example.

As somebody that has written hundreds of specs and PRDs over the years, I think one of the counter-intuitive things about doing it well is that there is no such thing as a "properly written spec". Or more accurately, "properly written" isn't a single path. You can't really templatize this in a generic way.

Instead, I'd offer the following basic advice which will help to build good specs:

1. Create an outline first, enumerate the list of stakeholders and the sections/topics that those stakeholders are most interested in addressing. Use this outline as the basis for filling in the details.

2. Don't write more than you have to. Rather than being overly verbose, establish the context of what/why/when at the top of the document in a summary, and then focus only on the most relevant conclusory details in each section after. The more shared domain knowledge the stakeholders have, the less you have to write.

3. A good spec results in a finished product/feature/widget. Be clear about what you know, what you don't know, and what you believe. Leave room for things to be discovered during implementation. Be concise.

Basically, don't write more than is necessary to actually achieve what the output of the spec is trying to achieve given the team/organizational context that the spec is going to be used in. Be as concise as possible, eschewing verbosity when possible because shared knowledge already exists. For this reason, "properly written specs" are very team/organization/project/product/person dependent. There's no universal format that works.

This is a nice essay introduction depending on the type of spec you want to write:

https://www.joelonsoftware.com/2000/10/02/painless-functiona...

From personal experience, i can suggest;

* RFCs on IPSec.

* ITU Recommendation on H.323 Protocol for Packet Based Multimedia Systems.

* The NIST documentations on FIPS and the various Crypto algorithms.

The first two are an "umbrella" of protocols and thus the specifications go from overview to extremely detailed in a very nice step-by-step manner. The third one shows you how to specify detailed and complicated algorithms.

Writing good Specifications is extremely demanding! But this is the only way to really understand the Domain.

Reply on news.ycombinator.com