diff --git a/docSystem.adoc b/docSystem.adoc new file mode 100644 index 0000000..e3baed3 --- /dev/null +++ b/docSystem.adoc @@ -0,0 +1,78 @@ +docSystems.adoc + + +- - - +_2023-10-18 12:03 chat w SteveZ_ + +I associate hierarchy with + +- The organization of a book, + - logical sequence of topics, + - simple to complex + - (book, chapter, verse,..) + +- Tree of life (sub-class relations) Kingdom,Phylum,C,O,F,Genus,Species https://images.squarespace-cdn.com/content/5f02d28f35d64d2a5022eeb1/ed2fcad4-bf94-494e-90cc-647d8943a630/30.png?format=1500w&content-type=image%2Fpng[] + +. + +- - - +I'd appreciate your reactions to some thoughts I had about the Grouper Survey Initial Recommendations: https://docs.google.com/document/d/1uWRomgUflT6Ec03vo-tL795XUUr2HdpU0WrVLZC-Yvs/edit?usp=sharing[] + +Page Warnings +- Experimental +- Since +- Deprecated +- Obsolete +- Replaced By +- Outdated + + +*- Steve Zoppi -* + +I have a similar "sense" of those taxonomies from the survey feedback too... + +I think that the missing "prescription" is how to maintain documentation in alignment with the version - so right now (the way you've written it up) it lacks the information hierarchy ands presumes "tagging" may be the primary means of categorizing a given article or document. + +The thing I'm wrestling with (in my head) is +- the _information hierarchy_ that encapsulates _each group_ of documents. + +I don't have good answers (yet) but I'm considering that there needs to be +- _two branches_ (at least) of hierarchy: +(1) Global/Persistent Concepts and Facilities artifacts/documents/articles +(2) Ephemeral/Version-bound artifacts/documents/articles. + +- - - +_2023-04-06 11:18:07 Setting up evolveum-like doc site_ + +https://docs.evolveum.com/about/jekyll-environment/[] <- install, config, build, run jekyll site + + +*- local jekyll instance of Evolveum Docs running: -* + +http://localhost:4000/ + + +- - - +_2023-04-04 11:28:40 adding commenting to a static site_ + +https://github.com/eduardoboucas/staticman[] <- open source commenting system + +https://staticman.net/docs/index.html[] + +https://mademistakes.com/mastering-jekyll/static-comments-improved/[] <- staticman plus + + +https://averagelinuxuser.com/static-website-commenting/[] + +https://docs.evolveum.com/about/jekyll-environment/[] + + +https://remark42.com/docs/getting-started/installation/[] + + +https://simondosda.github.io/posts/2021-09-13-blog-github-pages-1-introduction.html[] + +... + +https://simondosda.github.io/posts/2021-09-17-blog-github-pages-5-comment-1.html[] + +https://simondosda.github.io/posts/2021-09-18-blog-github-pages-6-comment-2.html[] + + +- - - +_2023-04-03 13:11:12 evolveum approach to documentation_ + +https://docs.evolveum.com/about/writing-documentation/[] <- ref manual for Evolveum Documentation + +https://docs.evolveum.com/about/jekyll-environment/[] <- setting up jekyll +https://github.com/Evolveum/docs/[] <- Source Code of Evolveum Documentation Site + +https://docs.evolveum.com/about/asciidoc/[] + + +- - - diff --git a/docs/ps2grouper.adoc b/docs/ps2grouper.adoc index b096fd4..a0d5d85 100644 --- a/docs/ps2grouper.adoc +++ b/docs/ps2grouper.adoc @@ -56,7 +56,7 @@ all of those are published. A group or many of them are then published to that t I should have said this before, but please interrupt with questions as we go along, because I know these paths are fairly divergent. -Q: So it's a really, really quick one about the diagram that you're showing that Are the arrows correct? Are you taking data from and from Fromatica and sending it to people talk? Or is it the other way? +Q: So it's a really, really quick one about the diagram that you're showing that Are the arrows correct? Are you taking data from and from Informatica and sending it to people talk? Or is it the other way? A: I debated which way to point these arrows, but this is our SQL query, so that is Informatica reaching out to Peoplesoft with the SQL query and pulling data back. diff --git a/grouperSurveyResponses.adoc b/grouperSurveyResponses.adoc new file mode 100644 index 0000000..900ca72 --- /dev/null +++ b/grouperSurveyResponses.adoc @@ -0,0 +1,22 @@ +=== grouperSurveyResponse.adoc + + +*- Responses to Grouper Survey Initial Recommentations -* + +Ensure that each 'page' or unit of documentation carries helpful metadata (tags, keywords, with a controlled vocabulary of primary terms) + +- type of documentation: How-to, tutorial, reference, explanation (ConOps) +- context: Deployment, Tech Dev & Integration, Administration, data structures, UI guides +- other keywords to support search terms +- versions to which documentation applies (e.g. Grouper >= 4.7) +- links to related documentation units +- date created, date last modified + +The above categories align fairly well with the responses to the "Improvement Priority" question on the Grouper Survey + +Keep in mind creation and maintenance costs when formulating documentation guidelines + +*- Harvest Slack problems posed and solutions offered on Slack; -* + +- Collect in a well-known, well-organized documentation resource +- Addresses the "Same question 100 times" problem