This is a read only archive of pad.okfn.org. See the
shutdown announcement
for details.
writethedocs-smartdocs
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
SMART DOCS
#adaptive
#autogenerated
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _
******************************************** Evaluating user profficiency
Computational hermeneutics
where do you keep the data #privacy
server
client
"What people have already done"
TinCan API
Measure profficiency
Environment state of the system
* metrics
* installed plugins
"Dump of the system/software instance state"
...and use this for adaptive docs
Auto-profficiency evaluation
"what has the user done"
As a user: defining what you want to achieve
Semantic tech is definitely a part
Bridging different ways of expression #ux
Build ontologies
******************************************** Hypernarratives -> Linear narratives
Related yesterday: Talk on computational hermeneutics
https://pad.okfn.org/p/writethedocs-comphermeneutics
-----------------------------
DITA is mentioned
Has "relations" between content chunks:
parent-child
...
DITA is too complex
"Lightweight DITA"
http://techwhirl.com/lightweight-dita-preview-michael-priestley/
#todo #ux #hypermedia
Could do:
Smart collapsing !!!!! <kris
"User has seen this"
Collapsing / Uncollapsing
------------------------------------------------------
This is basically about building TRAILS from chunks #hypernarrative
Anki / spaced repetition #ux
show and reshow chunks according to how well you remember them
Also Memrise
Software for turning chunks/Fragments -> Linear narratives
FluidTopics / AntiDot
Direct DITA/XML -> HTMl
http://www.fluidtopics.com/
middlemachine fragment engine
email david@middlemachine.com
Dita Drupal module <kris
Dita via drupal -> html
Dita To Web
http://intentionaldesign.ca/2013/07/01/dita-to-web-the-next-big-thing-part-1/
Easy DITA ...
Usually the simplest workfow:
DITA->Oxygen->...
#opensource is missing
Dita->publisher
************************************* Autogenerated documentation
Self-generated from code
especially for APIs
Doxygen, JavaDoc
WSDL
----------------------------
Problem:
how to get it from everywhere and publish on one spot? (Federation/syndication)
inter-linking of content of different sources
Currently:
Easiest via common XML
-------------------
A lot of bridge building #todo
Auto-prioritize maintenance work on articles:
(based on IMPORTANCE x -QUALITY)
look at https://pad.okfn.org/p/writethedocs-humantesting -> General priority equation for documents
Pooling all feedback together:
you could use #semantic tech to sort / cluster / prioritize it, again
Smart quality assesment tools:
As you write:
are you following style guides / linguistic checks:
Really expensive, 50k€ range
http://www.acrolinx.com/
these solutions have to be Tailor-made in a way
spelling
Zemanta-like
Tools:
Hemingway (assistive)
-----------------------
Something on a large-scale:
Like Mediawiki bots (autonomous)
Full-blown Documentation audit?
-----------------
MDN: they use a bunch of regexes
Idea #todo !!!!!!!!
Could we have a common collection of regexes?
MDN: they use macros: "5 or 6 of them"
Validation
Documentation validation
Enforcing rules -> System that pushes back, gives improvement/fix tickets !
"You need a good WYSIWYG editor":
should enforce DTD/schemas on the fly
...
----------------
Editors
http://ckeditor.com/
-------------
MDN: Uses a custom Firefox plugin (with regexes)
Code example checking
Making sure code examples in documents are not broken!
------------
this might require running test instances as parts of documentation
Walkhub.com
trails for navigating websites
can handle forms
Reactive documentation (using events):
continous integratition
-------------------------
Using event hooks:
IFTTT
---------------------------------------
Following social media:
Mozilla case: 50-100 tweets (with feedback) per day
Problem of trust of what these autonomous Agents do:
A) give them full autonomy to make changexs
B) ... but see what if it works: A/B checking
C) agents as assitance-tools
Bots / Mediawiki has them
Testable documentation