News for hackers. Stuff that matters.

A comment on Etsy’s experiment with immutable documentation.

Re:Etsy’s experiment with immutable documentation by swalsh on Thursday December 13, 2018 @02:38PM (#18675281)
I think the part about this that is truly successful, is the use of slack significantly lowers the transaction cost of adding the documentation. In a wiki, where there is a certain level of quality expected, you might make the decision to just move on with your life once you find the answer you need, as you've already wasted enough time. With this, however, it's so cheap to leave a breadcrumb it's just polite to do so.
[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by forapurpose on Thursday December 13, 2018 @05:56PM (#18676903)
> the use of slack significantly lowers the transaction cost of adding the documentation. In a wiki, where there is a certain level of quality expected ...

The wikis I've used also have slow editing interfaces because they have separate read and edit modes. Does anyone know of a modeless wiki, which probably means one that allows you to edit-in-place?

The problem with modes is that to edit something on a sizeable page you must,

1. Load the page in read mode

2. Read/search to locate the spot on the page where your edit goes, read the context around it, and plan the edit.

3. Load the page in edit mode

4. Read/search to locate the spot on the page where your edit goes

5. Type your edit

6. Reload the page in preview mode (a form of read mode)

7. Read/search to locate your edit and verify it

8-?. Repeat steps 5-7 until your edit is correct.

N. Reload the page in read mode.

Compare to a modeless wiki:

1. Load the page in read mode

2. Read/search to locate the spot on the page where your edit goes, read the context around it, and plan the edit.

3. Edit until satisfied

[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by bjoernm on Friday December 14, 2018 @05:28AM (#18679829)
Have a look at Nuclino (https://www.nuclino.com), essentially a real-time wiki for teams. We're eliminating modes the way you describe in order to speed up the workflow. It supports edit-in-place, changes are automatically saved and you can collaborate in real-time (like in Google Docs), but you also have core wiki features like easy linking and consistent styles.
[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by closeparen on Thursday December 13, 2018 @06:57PM (#18677261)
Google Docs. Has comments, too.
[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by forapurpose on Friday December 14, 2018 @12:07AM (#18678606)
How easy and efficient are other wiki functions, such as creating hyperlinks between documents, creating new documents, and a simple, structured style system? Last time I looked at it for these purposes, Google Docs failed in those areas.
[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by gowld on Thursday December 13, 2018 @04:40PM (#18676385)
That's sad to read, since Wiki was originally invented to create a simple user-editable document, to solve the problem of "just move on with your life once you find the answer you need, as you've already wasted enough time"
[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by darkerside on Thursday December 13, 2018 @09:22PM (#18677931)
This is just the next iteration following the same pattern down its logical path. Assuredly at some point in the future, we'll find another faster and more convenient way to convert real-time answers into documentation, and we'll seize it.
[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by adjkant on Thursday December 13, 2018 @05:03PM (#18676544)
Quip has a great interface for documentation/instructions and easily leaving comments, would highly recommend it.

https://quip.com/

Disclaimer: Nothing to do with them, just at a company that uses it and finds it very good at this part of docs

[ Parent | on HN ]
Re:Etsy’s experiment with immutable documentation by DEADBEEFC0FFEE on Thursday December 13, 2018 @05:04PM (#18676547)
Interesting that you used the verb wasted, and not invested.
[ Parent | on HN ]