parity-signer
parity-signer copied to clipboard
novasamatech
Fill the documentation with up-to-date screenshots
Maybe there is a way to automatically generate those on testing flow? They've gone unusably outdated several times over the history of this repository.
Well, it's not fully clear if obsolete documentation is better with up-to-date screenshots or with matching obsolete ones... Of course autogeneration would be a positive change for tiny changes — but at the price of making it only worse for everyone in case of major reshuffles (or, alternatively, significantly increasing our maintenance burden with checking and updating the written docs on every change, prior to release).
Where are we even hosting said documentation? Do we have any stats of whether people are actually using it? I would suggest that currently there's usually little expectation of some hosted documentation for webapps.
in case of major reshuffles
Well, yes, just throwing screenshots blindly would be silly; this should be some part of automatic tests CI flow, somewhat similar to in-docs assert! macro in Rust. It's just an idea that seems conceivable; not for the shortest term of course (hence no milestone/links). It these will be part of tests, the tests themselves will amortize most of burden.
Anyway, that's the research part. This issue is mainly about the screenshots in manuals being badly outdated. It is related to #795 but just a bit more complicated and less pressing (I think I'll just remove screenshots altogether for some time).
Where are we even hosting said documentation?
There are several places (some listed in Notion); this is one of them. People keep referring to "official manual from github" even here in issues and more so in personal conversations (screenshots are in the repository, which is not perfect and one of the things that should change). Github manual seems to be very important. Manual on wiki.polkadot.network is also popular. And the screenshots help lots of people to find the way, even though the Signer is getting simpler, we still need some visual guide for quit a visual tool.
Well, I guess there's https://openqa.opensuse.org/, which can do computer vision-based tests — but never seen it being used for mobile apps testing tbh; also setting all this up is going to be a huge project. I'd suggest postponing it for now.
Initiating a one-time Github manual update project would be great, but is not necessarily a strong prerequisite for the launch of the updated version; I'd suggest us shutting down all the existing ones to avoid confusion some time around our new updated version would get to a public beta.
Well, I guess there's https://openqa.opensuse.org/,
huh, that's a huge overkill. Normal mobile testing suites can detect screen elements and print screenshots - so we can just look at the latter and confirm that the manual makes sense, while the suite makes sure that the important elements are present on the screen. It's something I wanted to add to tests for a long time. But yes, I'll postpone it at least until we have really stable UI flows.