automerge / automerge/automerge.github.io

Reference->Lists code example is not in sync with comments describing the results of the operations

Open
#19 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
12
Forks
12
Avg merge
1d 12h
Merged PRs (30d)
4

Description

The code example in the [Lists section of the reference docs](https://automerge.org/docs/reference/documents/lists/) is misleading. The example transformations presented do not reflect what's written in the comments.

The code vs. comment discrepancy starts in [this line](
https://github.com/automerge/automerge.github.io/blob/main/content/docs/reference/documents/lists.md?plain=1#L18-L19)

Which splices the list at idx 2 removing 2 elements:

// now doc.list is [0, 2, 4, 6.283185307179586]
doc.list.splice(2, 2, "automerge");
// now doc.list is [0, 'hello', 'automerge', 4]

It's impossible to arrive at the result list just by using splice.

Running the same sequence (truncated above) in my browser console gives me a very different list

```
>> Automerge.change(Automerge.init(), (d) => { d.list = []; d.list.push(2,3); d.list.unshift(0,1); d.list[3] = Math.PI; for (let i =0; i Array(3) [ 0, 2, "automerge" ]
```

Subsequent lines make a bunch of further modifications, which are not self-explanatory, and we end up with

```
[0,'hello','world',2,4]
```

I tried rewriting this section locally to make a PR, but I'm not quite sure how to get from-here-to-there, i.e which operations (or comments) to re-write. So instead I'm just flagging this as a exposition/clarity bug in the docs.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with content/docs/reference/documents/lists.md around lines 18-19 and read the complete Lists example, including the later transformations. Run the sequence in a browser console and compare each operation with its comment; done when the executable example and all documented intermediate and final lists agree.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
Half a day
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.