Recommendation: modify documentation to support "easing" into mackup

[sdondley]

I'm new to mackup and like what I see. However, I think the documentation could be more clear and do a better job of ensuring the user does not get in over their head, especially if they intend to use mackup as a two-way sync across different machines, which can be much more problematic.

The documentation should make clear that there are two different major use cases:

1. You have a "master" machine that distributes its configurations over to "slave" machines. For example, if I have a desktop that I do most of my work on and a laptop that I occasionally work on, I would typically never make any configuration changes on the laptop. All modifications flow from the master to the slave machines and you don't need to have custom configurations for each machine. This is the simplest scenario.

In the quickstart section of the docs, it has the user to do a full backup and restore of all supported config files and apps. This is probably a bad idea, especially for someone in scenario 2 (see below). The documentation should point this out and recommend a more fine-tuned approach and recommend the user create a .mackup.cfg and start with syncing just a single application (bash might be a good candidate because it is probably on 90% of machines). Then as the user gets more comfortable with mackup, they can start adding other applications.

2. You have two existing machines that have two different config files that you want to sync up. Let's say a developer has two different machines and that Machine A has a very different vim configuration than Machine B. The developer wishes to deploy mackup to fix this problem so she can have the same vim environment on both machines.

I am a person with scenario 2. And it took me a bit to realize that the documentation, as written, does not help me to realize that I should resolve the existing conflicts between my two machines before using this tool. I think the documentation should make this abundantly clear and recommend ways to get their files synchronized before doing a backup and restore.

I'd be happy to contribute to the documentation to try to improve this but I wanted to confer with the maintainers first and get their input.

[lra]

That's all reasonable and you have my blessing. My only ask would be to keep the main use case simple and concise and keep the most complex use cases deeper in the doc, to not scare most users.

[sdondley]

Yes, that is my intention.

…

On Mon, Aug 20, 2018 at 12:50 PM Laurent Raufaste ***@***.***> wrote: That's all reasonable and you have my blessing. My only ask would be to keep the main use case simple and concise and keep the most complex use cases deeper in the doc, to not scare most users. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1203 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACY-fIL68nnIZWI5FbJf1MAfGBv8F-LPks5uSuixgaJpZM4WEV1v> .

-- Prometheus Labor Communications, Inc. http://prometheuslabor.com 413-572-1300 Communicate or Die: American Labor Unions and the Internet http://communicateordie.com

[sdondley]

See #1205 and #1204