<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>Hi everyone,</div><div><br></div><div>At yesterday's community meeting we discussed the Infusion documentation and made some decisions for what we will be doing with it. Our current documentation has portions that are out of date and misleading. This is for a number of reasons, including the sheer quantity of the current docs and the fast rate of change that the framework has been undergoing. We are currently at the point where it is difficult to know which docs are up to date and which require updating. We have also been discussing for some time a change in strategy for how we make our docs and where we keep them. </div><div><br></div><div>We decided: </div><div><br></div><div>1. We will start storing our documentation in github: <a href="https://github.com/fluid-project/infusion-docs">https://github.com/fluid-project/infusion-docs</a></div><div>2. We will mark the current documentation as out of date and move only the accurate docs into the github repo.</div><div>3. API style documentation will be moved into the source code.</div><div>4. New documentation will be written using Markdown and organized as a flat hierarchy of topic specific pages.</div><div>5. New pull requests to the code base will need to be accompanied by a pull request to the documentation with the appropriate changes.</div><div>6. The documentation working group will review new features coming into the framework and the documentation for them. That group is currently comprised of Antranig, Simon, Anastasia and me.</div><div><br></div><div><br></div><div>We also discussed some ideas for what we would like our documentation to consist of. See the notes below:</div><div><br></div><div><br></div><div><br></div><div><div class="ace-line" id="magicdomid64"><span class="b"><b>Three types of documentation, from the top down:</b></span></div><div class="ace-line" id="magicdomid65"><ul class="list-bullet1"><li><span class="">A reference guide (definitive explanation of what's in the framework)</span></li><ul><li>This is different from what  other software projects have in that we have moved away from having APIs</li><li>Consists of descriptions of the various kinds of JSON configuration that is valid for different types of grades</li><li>As
 well as describing default values which are supplied by grades, it 
needs to describe what configuration is accepted by both grades and 
builtin piece of framework machinery</li><li>This
 also needs to include background information about different types of 
components (e.g. the Change Applier), what they're for, and how they 
work</li></ul></ul></div><div class="ace-line" id="magicdomid70"><ul class="list-bullet1"><li><span class="">The
 "how do I do X?" documentation (i.e. information that answers specific 
questions and is indexed by particular tasks or functionality)</span></li></ul></div><div class="ace-line" id="magicdomid71"><ul class="list-bullet1"><li><span class="">Concepts,
 goals, intent and style documentation that provides the "big picture" 
view of the goals and intention of our framework design (examples 
include, perhaps, the </span><span class="i"><i>Being and Time</i></span><span class=""> wiki page)</span></li><ul><li>Another example of this is the background information that explains our approach to, say, APIs and their alternatives</li><li>This
 kind of documentation isn't just "background information," but equally 
important as part of understanding why the system is the way it is and 
how you should use it.</li><li>"Speaking like a native" documentation that describes the "natural" or idiomatic ways to develop with Infusion</li></ul></ul></div><div class="ace-line" id="magicdomid78"><div><br></div><div>As always, comments, corrections, questions and suggestions are welcome. :)</div><div><br></div><div>Thanks,</div><div><br></div><div>Michelle</div></div></div></body></html>