Improve the documentation

[rohanprabhu]

I have recently started using remote-browser and when I was working on it, I realized that the documentation is extremely lacking and it took me snooping around the code a lot of time to figure out what's happening.

Towards that effort, I would like to work on the documentation for this project and hence creating this issue so that we can discuss what all needs to be covered. A list of topics off the top of my head are:

1. Setting up the browser extension
2. How to pass arguments to the evaluateInContent function and the rationale behind why variables are not closed-over. This one took me quite some time to figure out till I realized that the function is serialized and sent over to the browser. In retrospect, it looks quite obvious, but would be very deterring to new users.
3. A troubleshooting guide to wait for document loads. I am not sure how the evaluator.readyState works, but it didn't work for me. I am using a kind-of hack to wait before proceeding:

function waitFor(browser, tabId, elementLookupList) {
    return new Promise(resolve => {
        const interval = setInterval(checkForElements, 500);

        function checkForElements() {
            const allReadyPromise = elementLookupList.map(ele => {
                return browser[tabId](ele);
            })

            Promise.all(allReadyPromise)
                .then((elements) => {
                    if (elements.every(x => x)) {
                        resolve();
                    }
                })
        }
    });
}

// USAGE
await waitFor(browser, tabId, [
     () => document.getElementById('fldLoginUserId') != null,
     () => document.querySelectorAll("input[name='fldSubmit'][value='Continue']").length === 1
]);

4. A few more examples of what can be done. I really like the format of the small video you have created to show a live session with a running browser. If the documentation can improve on the process, it would get a lot of people invested very quickly (or so is what I think).

I was thinking of starting with some basic additions to the current README, maybe add more details to each section - especially places where I got stuck and then move on to a caveats guide as well. Before starting, I'll share a quick outline of what I am thinking about the documentation and once we both agree that it looks good, I'll write it out and submit a PR.

Please let me know what else you think can be useful and should be included in the documentation and I'll work on the outline accordingly.

[sangaline]

Have you taken a look at the interactive Remote Browser tour? It goes into much more detail than the README, and it allows you to run working examples in your browser.

It would be great to improve the documentation, and we would greatly appreciate your contributions here. Our general thoughts on the README is that it should serve as a relatively concise overview of the project. That's why the tour exists as a separate project to cover how things work in more depth than the README. We think that the sort of additions that you're discussing would work best if we introduce some organizational hierarchy in the project. One way to do this would be to have a docs/ directory that contains markdown files that focus on different examples (e.g. examples, troubleshooting). Another option would be to do something similar using GitHub's built-in wiki functionality. It would be even better if we could reuse the tour's infrastructure to include more examples, but that would require significantly more effort.

It would also be great to see third-party guides and tutorials relating to Remote Browser. We would be happy to link to these from the README, and could host them on the Intoli blog if someone doesn't have a blog of their own.

[rohanprabhu]

So somehow I did go through the remote browser tour and yet missed the little details that I mentioned in this issue. I could think of a few topics and write a more detailed doc and we can take a call on linking it or hosting it.

However, prior to that, is there anything that you would like me to contribute to in this project itself? Maybe a reference documentation? So, when I did create this issue it wasn't about improving just the README, but overall providing exhaustive documentation of all features. I am currently not aware of the entire codebase, but can pick up specific topics which we might think are important and would love to contribute. Let me know what you think

[sangaline]

Hey @rohanprabhu, sorry for the slow response here. This is definitely still something that we want to pursue. Because so much of the functionality of the library is provided by the Web Extensions API, I think that the most useful contributions at this point would be more comprehensive test coverage and documentation examples. There was recently an issue (#71) where somebody tried to do request interception and ran into a bug/limitation of the serialization. Realistically, there are probably more issues of this nature out there. I think that adding documentation/examples for specific use-cases and writing corresponding tests would likely turn up some of this areas that need more polish.

[rohanprabhu]

That sounds like a good idea. Sorry for the delay from my side too, I have been very busy with work. Let me take this weekend and I'll try to come up with a list of things I think can be addressed and then we can discuss them further?

[sangaline]

Sounds good!

[klaussa]

Dear @sangaline,

Is the project still maintained ?

Kind Regards
K