Documenting framework changes

Cheetham, Anastasia acheetham at ocadu.ca
Fri Feb 22 16:39:43 EST 2013


I've been reviewing all the information that's come out of our various sessions discussing the recent framework changes with an eye to ensuring that these changes are adequately documented.

I will be putting together an "Infusion Best Practices" document that summarizes our guidelines and recommendations for writing components, but I also need to document the specific API changes. Currently in the documentation, if some feature is introduced in a particular version, it is marked with a phrase such as "New in v1.4"  Our latest changes, though, have not yet been released in any way; they exist only in our master branch. This doesn't mean that we don't need to document them, though: People are using our master branch, and they could use some docs.

So I'm looking to the community for suggestions for how to manage these updates to the documentation. Should we

- mark changes with "New in v1.5" (or whatever the version number will be when it is eventually released)?

- mark changes as "New in master" (which would need to be updated when we eventually release)?

- mark changes with some other indication?

- not actually update the relevant pages yet, but provide a single list of API changes (like a changelog)? (personally, I don't like this idea since people will likely not know it's there)

- other suggestions?


Thanks for your help.

-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocadu.ca           Inclusive Design Institute
                                        OCAD University



More information about the fluid-work mailing list