On 10/24/2016 01:33 PM, Scott Doctor wrote: [snip] > I think the documentation should group the most commonly used commands > from the master list. Maybe make several groups presented in most-used > to rarely-used groupings. A primer should avoid permuting the possible > operations until later (it just adds to the confusion) and focus on a > complete real example with the concepts explained as though the reader > is seeing it for the very first time. [snip] > The documentation needs a newbie primer that better explains how commits > and syncing works. I now mostly figured it out, but was initially > discouraged because of the seemingly (incorrect) concept of operation > for syncing with the main repository. > > A problem with most manuals for many software products is that an > assumption is made that the reader already understands the concept of > operation. If the reader is confuzzled at the start, then explanations > of the commands do not absorb without an understanding why it is being > done.
Déjà vu http://www.mail-archive.com/search?l=fossil-users%40lists.fossil-scm.org&q=subject:%22\[fossil\-users\]+Pedagogy+Think+Tank+or+Documentation+Framework+RFC%22&o=newest But there isn't much of a feedback mechanism in the software engineering process to harness and utilize this information - it's still all done in a willy-nilly, back-channel, human-toil fashion. C'est la vie _______________________________________________ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
