Comment by twodave | Hacker News Reader

Comment by twodave | Hacker News Reader

The most useful part of writing docs for me is that they shine a spotlight the sharp edges of your product. Why is this feature so hard to document? Oh, because it sucks! Let's make it better, and then the docs will make sense too.

At work I sometimes frame discussions about new features in terms of how I'd describe using this new feature to different users of our product. If it isn't straightforward given the context then it probably isn't a well-developed idea, yet.

One notable example--we (a payroll platform product team) needed a better way for users to fix mistakes in checks they'd already committed to the system. We have a non-negotiable stance that says we don't edit transactions. We can add new ones to cancel out the old ones, but we don't edit stuff that's already happened. This gets really confusing to users when they're trying to change a $200 to a $50 and need to commit a -$150 transaction someplace (and then also adjust all the other things downstream from that, like deductions/taxes/etc).

So we built the "time machine". Using this feature, users can type in the $50 and let the system figure out what transactions need to be added. There's a lot of complexity in the phrase "let the system figure out" but that's sort of the point. Now our tutorial on making payroll adjustments literally says "1. Find the check you want to adjust, 2. Click 'Adjust', 3. Type in the new number and 4. Click 'Finish'".

> Our habit of trying to document bugs and limitations visibly was enormously useful to the system. As we put out each edition, the presence of these sections shamed us into fixing innumerable things rather than exhibiting them in public. I remember clearly adding or editing many of these sections, then saying to myself "I can't write this," and fixing the code instead.

~ Dennis Ritchie, on the BUGS section of UNIX Manuals

Amazon does this a lot in their “customer obsession” management strategy. In their terms, the mechanism to make this happen is called a “PR/FAQ”[1], and the core idea is that if you can’t express your idea in terms of a customer-focused press release, then it isn’t a good thing to add.

[1]: https://productstrategy.co/working-backwards-the-amazon-prfa...

I find it incredibly useful to do this with code too!

If you’re managing a service/library that other humans integrate with, write some fake integration code as if you are one of those other humans. I don’t mean end-to-end tests, this is even dumber than that, and must be done _way_ before codifying behavior with tests coverage to avoid future regression.

Is the integration clunky, or worse, are some interactions not even possible? This exercise will shine a sobering light on such sharp edges. Would one small interface change eliminate 30 lines of frequently duplicated integration code? Is required functionality missing?

It is difficult to surface all such usability issues in a vacuum, but they surface very naturally when actually using the tool that you are building— even if it’s all made up so far. Remember, this is for people to _use_, not a piece of art to be observed but never touched.

Put into metaphor: don’t build the world’s fastest car and omit the steering wheel, gas and break pedals, seats, doors, windows, mirrors, etc., all because you never stopped to think about how someone might _drive_ the damn thing.

> The most useful part of writing docs for me is that they shine a spotlight the sharp edges of your product.

I love this. I have written docs for dev tools companies and one section I love to write is the limitations section, especially if I am new to the product. This is helpful in so many ways.

* It lets me as a writer understand the built in limitations.

* It helps the team building the product get on the same page about areas to improve (or areas that are explicitly limited for business purposes)

* It helps with credibility for devs, as they can immediately determine if there a limitation that isa deal breaker.

The hard part is keeping it up to date, but that's true of most docs.

I would make a -$200 transaction whose breakdown with deductions and taxes and whatnot are all mirror images of the original $200. It exactly cancels the incorrect original transaction to zero across all accounts in the ledger. This is followed by the $50 is a new, independent transaction. No brainer to understand, or audit.

That's what supermarkets do. They void transactions (usually needing a supervisor's approval) and then re-enter the purchase correctly.

In some situations this is ok. But if money actually changed hands then you can’t pretend you didn’t pay someone, so you’ve got to essentially create a debt or a new check, depending on whether the new total is negative or not. And that means all those new amounts may now need a different effective date. And each state can have different rules about collecting overpayments back from employees (some simply don’t allow it). We deal with staffing companies where folks forget to fill out Friday or fat-finger something on their timesheet, and we get it 2-4 pay cycles late, mixed in with other corrections and adjustments. There’s quite a lot of specialized logic involved.

I would say that all the additional complications make it even more imperative not to conflate the cancellation with the correction (another source of complexity into the mix), but do a clean cancel (as much as possible) followed by a reissue.

If there is any problem with the $200 cancellation, that has no effect on the correctness of the $50 reissue, which is entirely independent. It's easier to reason about problems with the $200 cancelation. Ideally, all affected accounts should be reimbursed as if the original never happened. If some account is debited $12.34 and then later credited $12.34, that's easy to match up and verify.

Obviously that’s the ideal situation. But in cases where you’ve already deposited funds you can’t pretend you didn’t.

I'm saying: do exactly what you would with the $150 offset, but use $200 to make it a complete offset. I don't see how it helps to work with $150 than $200.

> Why is this feature so hard to document? Oh, because it sucks! Let's make it better, and then the docs will make sense too.

I'm no UI/UX expert. But in writing documentation, I can clearly see messed-up UI stuff in general, and broken or incompletely implemented UI concepts in particular, and I can communicate these problems to the SW people, and get buy-in AND a proposed fix before I even file an issue.

This is actually another key concept that I've been mulling how to write about. There is a direct path from docs to support and into your product cycle. The information that flows through there should be critical to informing how your next feature set you develop is selected. Obvious, painful rough edges should be fixed.

This is true. I have often encountered design deficiencies, while documenting my work.

Reply on news.ycombinator.com