Hi. I have started working on refactoring the assembly/class loading in mono, and will be writing some conceptual documentation as part of this project. Because of this I am interested in trying to clean up the situation with the mono runtime’s documentation, which I feel is a little messy. At the moment, all of the design documentation for mono is in a separate repository from the source, https://github.com/mono/website , which is published on the web directly to http://www.mono-project.com/ using Github Pages. There are three big problems I see:
- The documentation is not versioned. There is a git history for the website repo, but if you have a copy of the mono repo there is no way to relate a particular revision of mono (or even a particular major release) to a specific version of the website docs. - There are still some docs in the main mono repository, under docs/, which were never moved over to the website. These are almost all inaccurate now. - The embedding API for the runtime is not documented on the web. There is doxygen in the source, and it is possible to build HTML from that source, but the mono project does not do this officially. I would like to do something about at least the first two of these problems in the short term. The stale docs problem is easy: Delete the stale docs. The first problem on the other hand seems to have multiple possible solutions, so Rodrigo asked I put a request for comments on the mailing list. After discussing this with a couple of people at Xamarin, here are the potential solutions I see to the versioning problem: 1. The simple approach: Put a line in docs/README in the mono repo specifically listing (or linking on Github) the git commit in the website repo which documents that version. We would then make it part of the mono release process to always update this link before tagging/tarballing. 2. Manually embed versioning information in the docs themselves: Start writing the website documents in such a way that each one contains text like “the following applies to version 4.4” or “this paragraph is true as of 4.2.1 or later”. If a document changes significantly, the out-of-date information could be moved to a /archived or /historical section within the docs directory. 3. Move the runtime docs back from the website repo to the mono repo, so that the docs and runtime are versioned in lockstep again, but have an export process where at certain times (such as a release) the current state is copied to the website. Probably only some parts of the website docs would be exported in this way (for example, docs/advanced and docs/compiling-mono on the website would be mirrors of folders in the mono repo, but the gui and database folders on the website would not be). 4. Do something with git submodules. Instead of manually copying files, we could make a new mono-docs repo on github, make this a submodule of the mono repo inside docs/, and also make it a submodule of the website repo inside docs/. Github Pages allows submodules inside of the gh-pages repo as long as the submodule is set up read-only. This would be like the “export” option, but instead of copying many files we would just have to update the submodule state on the website every so often. I think my suggestion would be to start with “option 1” immediately, and then plan to transition to option 3 as soon as practical. I like option 3 because it separates the “product” of the website from the working state of the mono repo (at the moment, if I want to create a half-finished document describing something that only exists in the master branch, there is no good place to put it), and because option 3 is easy to build further work on later. For example, if we had an export-to-website process, part of the export process could be to build doxygen and copy it to the website also, or to back up the old state of the docs to something like an /archived/4.3 directory within the website. (Starting to adopt a style of being specific about versions when writing documentation, as in option 2, would of course also be a good idea on its own.) What do people think about all this? - Andi
_______________________________________________ Mono-devel-list mailing list Mono-devel-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-devel-list