Given the vast technical resources that are available (and becoming available), documentation creation and refinement seems like a keystone technology. Dedicating weeks or months to evaluate a piece of technology is increasingly becoming a less viable practice. It's something that I've thought about occasionally during the last year, and I recall making plenty of notes on the subject but those notes are buried in an ~30GB pile of files with other notes. (I record my contemplative, speculative, insightful notes in speech form in audio/mp3 files).
I've noticed that "Fossil is a distributed NoSQL database"[1]. [1]: https://www.fossil-scm.org/fossil/doc/trunk/www/theory1.wiki And that there are "fourteen application-defined SQL functions and two table-valued functions that are useful for managing JSON content stored in an SQLite database"[2]. [2]: https://www.sqlite.org/json1.html [1] is not easy to find, and [2] is not easy to understand or use. But with this it seems like I could create annotations for the multimedia data, stored in plain text files in JSON format. Those JSON files could be periodically scraped and assimilated into an SQLite database and then used to search/mine the multimedia corpus. If the JSON files are under distributed revision control, multiple people could create/modify annotations (this probably doesn't apply to my notes but the technique could be applied to any media archive). Anyway, the point is that this would be a nifty little set of scripts utilizing Tcl/Tk-SQLite-Fossil that would be tremendously useful [to me] and would be well within my ability to put together,,, if there were a different quality and style of documentation/reference-material. It's a little ironic that I don't have access to my notes on documentation style, structure, and generation methods because the current documentation is impeding the development of the tools I need to search the notes. Good times. Off the top of my head, and following Unix man page style somewhat, what if commands were documented like this: Relevant Definitions Description Example Explanation Rationale Were the Example is comprehensive and provides a complete context and is a demonstration of the 'best practices' and conventions. (A picture is worth a thousand words, so is an example/demonstration. Let people see it work. Give them what they need to experiment with it). If the Example is executable with a known outcome, its execution could be included (automated) in the Release Engineering process to determine the points where the documentation needs to be updated so that it maintains traction with the core software. The other big component is community involvement, but I suspect this post is already too long to digest. Has anyone else thought about these issues? _______________________________________________ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
