Re: [fossil-users] Pedagogy Think Tank or Documentation Framework RFC

[Adam Jensen]

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

[Adam Jensen]

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

[Ron W]

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

[Ron W]

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

[Adam Jensen]

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

[jungle Boogie]

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

[Adam Jensen]

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

[fossil-users] Pedagogy Think Tank or Documentation Framework RFC

[Adam Jensen]

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