Infusion Documentation

[Michelle]

Hi everyone,

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. 

We decided: 

1. We will start storing our documentation in github: https://github.com/fluid-project/infusion-docs
2. We will mark the current documentation as out of date and move only the accurate docs into the github repo.
3. API style documentation will be moved into the source code.
4. New documentation will be written using Markdown and organized as a flat hierarchy of topic specific pages.
5. New pull requests to the code base will need to be accompanied by a pull request to the documentation with the appropriate changes.
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.


We also discussed some ideas for what we would like our documentation to consist of. See the notes below:



Three types of documentation, from the top down:
A reference guide (definitive explanation of what's in the framework)
This is different from what  other software projects have in that we have moved away from having APIs
Consists of descriptions of the various kinds of JSON configuration that is valid for different types of grades
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
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
The "how do I do X?" documentation (i.e. information that answers specific questions and is indexed by particular tasks or functionality)
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 Being and Time wiki page)
Another example of this is the background information that explains our approach to, say, APIs and their alternatives
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.
"Speaking like a native" documentation that describes the "natural" or idiomatic ways to develop with Infusion

As always, comments, corrections, questions and suggestions are welcome. :)

Thanks,

Michelle
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20140410/d1cdc7ef/attachment.htm>