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
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
