Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
Concerning the actual contents of a documentation system, I suppose a framework might be composed of templates for: 1. Command syntax quick reference - fossil help ?cmd? 2. Command detailed reference 3. Cookbook-like containing "recipes" for various scenarios 4. Overview 4a. System introduction - purpose, requirements, various metrics 4b. Conventions, organization 5. Tutorials - user, maintainer, developer An item 2 template might be structured like this: > Relevant Definitions > Description > Example > Explanation > Rationale Where the Examples might be excerpts from various Cookbook recipes (with meta-data defining any dependency relations to source code and/or other parts of the documentation). Templates for the metrics of 4a could get interesting (possibly tying into a test suite and/or incorporating user statistics). The idea is to provide system engineers with relevant data and quantified decision points upfront. Item 5 is tricky. Would there need to be an underlying/intermediate knowledge-base or would it be sufficient to have direct dependency relations to the source? ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
On 10/11/2016 08:31 PM, Ron W wrote: > Sounds like something Google Docs does or could easily do (at least in > Google docs for Business). I'm not familiar with any recent incarnation of Google Docs. A quick glance at my white board and I see four loops of interaction with the documentation system: 1. Developers - creation 2. Maintainers - modification 3. Users - annotation 4. SRC/runtime - verification Each of those loops [in my current view] would involve data collection and analysis with hooks into the [policy automation][1] system and ticket system. [1]: https://www.youtube.com/watch?v=B9pulMZwUUY "Checklists For Better Software" Item 4 in that list is rich with possibilities; e.g., examples & demonstrations within the documentation could be executed and assessed, there could be meta-data within the documentation expressing various dependency relations to sections or areas of the source code, etc. ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
On Tue, Oct 11, 2016 at 6:19 PM, Adam Jensen wrote: > On 10/11/2016 03:39 PM, jungle Boogie wrote: > > I would call that a wiki, not only inside fossil-scm but in general. > > I am inclined to think that a wiki probably isn't sufficient for many > projects. What I am casually proposing (just brainstorming, really) is a > documentation framework that supports several different types of user > (annotation) and developer (modification) involvement, all regulated by > policy automation and human/system assessment, modeling and analysis. > Sounds like something Google Docs does or could easily do (at least in Google docs for Business). ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
On Tue, Oct 11, 2016 at 6:19 PM, Adam Jensen wrote: > On 10/11/2016 03:39 PM, jungle Boogie wrote: > > I would call that a wiki, not only inside fossil-scm but in general. > > I am inclined to think that a wiki probably isn't sufficient for many > projects. What I am casually proposing (just brainstorming, really) is a > documentation framework that supports several different types of user > (annotation) and developer (modification) involvement, all regulated by > policy automation and human/system assessment, modeling and analysis. > (Too much razzle-dazzle?) > > I started to sketch some diagrams earlier but ended up exploring > [something like] enterprise architectures for various > developer(s)/maintainer(s)/user(s) social organization. (See the work of > [Max Weber][1] and [Karl Müller][2]). > > [1]: https://en.wikipedia.org/wiki/Tripartite_classification_of_authority > [2]: https://en.wikipedia.org/wiki/Karl_H._M%C3%BCller > > Making the operations (policies, procedures, etc) of the system > explicit, and the assessments and measurements quantifiable, all with > significant automation support, once bootstrapped, a project could > continue with little human involvement. If the documentation system > includes pedagogical information and methods sufficient to train users > to be maintainers and developers, such a project could endure the > vicissitudes of interest. > > ___ > fossil-users mailing list > fossil-users@lists.fossil-scm.org > http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users > ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
On 10/11/2016 03:39 PM, jungle Boogie wrote: > I would call that a wiki, not only inside fossil-scm but in general. I am inclined to think that a wiki probably isn't sufficient for many projects. What I am casually proposing (just brainstorming, really) is a documentation framework that supports several different types of user (annotation) and developer (modification) involvement, all regulated by policy automation and human/system assessment, modeling and analysis. (Too much razzle-dazzle?) I started to sketch some diagrams earlier but ended up exploring [something like] enterprise architectures for various developer(s)/maintainer(s)/user(s) social organization. (See the work of [Max Weber][1] and [Karl Müller][2]). [1]: https://en.wikipedia.org/wiki/Tripartite_classification_of_authority [2]: https://en.wikipedia.org/wiki/Karl_H._M%C3%BCller Making the operations (policies, procedures, etc) of the system explicit, and the assessments and measurements quantifiable, all with significant automation support, once bootstrapped, a project could continue with little human involvement. If the documentation system includes pedagogical information and methods sufficient to train users to be maintainers and developers, such a project could endure the vicissitudes of interest. ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
On 11 October 2016 at 12:12, Adam Jensen wrote: > If a documentation framework included an interface that would enable > users to provide feedback in a variety of ways (e.g., annotations, > comments, ratings, etc.) that might be useful information. I would call that a wiki, not only inside fossil-scm but in general. -- --- inum: 883510009027723 sip: jungleboo...@sip2sip.info ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC
Here's an idea that might be a little complicated to describe: Every time a [potential] user interacts with the documentation there is human attention, intelligence, and effort that is engaging the system. What if the system were designed to harness some of that? If a documentation framework included an interface that would enable users to provide feedback in a variety of ways (e.g., annotations, comments, ratings, etc.) that might be useful information. If a user is known, their feedback could be qualified or weighted in some way based on [expectations generated from] their history. If that analysis were automated and tied into the ticket system, developers and maintainers would only need to address fairly abstract alerts. Developer interaction with the ticket system could then provide feedback to the analysis system but I suspect I am probably way off the reservation at this point. Also, I suspect some kind of rules engine would need to be integrated, either embedded or as an extension. ___ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
