WIP: describe concepts first. #123
Conversation
The readme has a great, concise introduction, but the Usage section jumps pretty hard into "first run" specifics without explaining some needed background information. I feel like there should be some conceptual descriptions before getting into the specifics of the commands to run. Defining some concepts and terms early on means the rest of the docs can be less verbose. This is an initial attempt at doing so, and while doing it, it made sense to move the modus operandi into it. I'm filing this PR as a starting point for a conversation around it, it should not be merged as is. this builds up understanding more logically (but people can still jump ahead if they choose to using the TOC). Looking forward, we should probably split up some stuff into separate pages. E.g: * keep the README lean / headline stuff. * separate page: tutorial / first run * separate page for concepts deep dive * separate howto's (e.g. ignoring files, scripting) * separate page for comparison to other systems
|
Thank you for this PR; documentation improvements based on others' experience with it are very valuable contributions. I am hesitant about adding a terminology section before the first run section. I feel like there is a significant group of users (and I would consider myself in that group) who would be immediately put off from the impression that they have to read and understand a tool's documentation in order to be able to use the tool (relevant xkcd). Instead, aconfmgr reasonably tries to guide first-time users who are going in "blind" by detecting common situations and offering suggestions (e.g. if there are no ignore rules, it will print a warning if there is a suspiciously large number of stray files, or if some stray files are very large, and further suggest a line to add to the configuration). Not sure about splitting up the documentation. Though I agree it's unusual to have it all in the README, it does seem to work well from a technical standpoint - splitting it up across multiple files would add friction in locating it and navigating across it. Are there any arguments in favor of splitting it up in separate pages? It's a bit difficult to discern the other changes from the diff right now. Would you mind placing the change that moves text around in its own commit, without anything else (or reverting it)? |
The readme has a great, concise introduction, but the Usage section
jumps pretty hard into "first run" specifics without explaining
some needed background information. I feel like there should be
some conceptual descriptions before getting into the specifics of
the commands to run. Defining some concepts and terms early on
means the rest of the docs can be less verbose.
This is an initial attempt at doing so, and while doing it,
it made sense to move the modus operandi into it.
I'm filing this PR as a starting point for a conversation around it,
it should not be merged as is.
this builds up understanding more logically
(but people can still jump ahead if they choose to using the TOC).
Looking forward, we should probably split up some stuff into separate
pages. E.g:
Note: because i moved a bunch of the text from modus operandi, the diff shown makes it look like i completely took down and rewrote the "first run" section, but that section actually didn't change much.