[Mono-dev] Clarifying the relationship between docs/ and the website

[Andi McClure]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ximian.com/pipermail/mono-devel-list/attachments/20151028/5a811ac7/attachment.html>