search

veeam / blksnap

Nonpersistent block device snapshot with block-level change-tracking capabilities.
GNU General Public License v2.0
84 stars 22 forks source link

Improve man and documentation #56

Open Fantu opened 1 year ago

Fantu commented 1 year ago

Description

Seems to me that actually man of blksnap tool and documentation is "minimal" and for understand how to use it "fast" is need for example to look to tests scripts and in some cases require also looking at the source code to understand better. I think can be useful to improve man and blksnap help texts to make easier and faster do common blksnap usage. It might also be helpful to do some small howto's of some common usage examples. Looking for example the man recently added in stable-2.0 an explanation could be made regarding "stretch_snapshot" which I think is quite important. "snapshot_create" and "snapshot_add" they would seem unclear at first glance, they don't take the actual snapshot (done by "snapshot_take") but they "prepare" to do it, maybe they could be called differently but I can't think of a clear name and maybe it's enough to specify better in the man and in the help of the tool, perhaps also specifying in "snapshot_take" that the preparation and addition of storage for the differences is required first. Unfortunately I'm not good at explaining and also write in English so I think many people could improve/add documentation better and faster. If it won't be done by other contributors, I would eventually try to do it.

Usage tips

SergeiShtepa commented 1 year ago

Yes. Creating high-quality documentation requires considerable effort. Alas, I can't cover everything. Any help is welcome.

SergeiShtepa commented 1 year ago

Hi. In the stable branch, I have significantly improved the man page. See: https://github.com/veeam/blksnap/blob/stable-v2.0/doc/blksnap.8 It seems to me that the documentation is quite good. I do not know what else could be improved. @Fantu, what do you think about this?

Fantu commented 1 year ago

@SergeiShtepa It seems to me that you have improved the documentation a lot, to know if it is sufficient we would need to see the opinion of some users. Unfortunately I'm not very good at documenting and explaining, and therefore I don't know if I'll give a good rating. In https://github.com/veeam/blksnap/pull/79 I readded at least a note on top of README I think essential for new users to know

SergeiShtepa commented 1 year ago

OK. Let it stay that way for now. Maybe in the future I or someone else will need to add something to the documentation and improve it.