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

Fri Nov 6 05:41:07 UTC 2015

Hey Andi,

He's my take on your suggestions.

We have a big gap in our docs story. It would be great if we got back to
publishing API and runtime docs together with
each release. That would solve the issue of making them available.

Moving them back to the mono repo creates some friction to publish them on
the website and, if anything, we want to
reduce any friction. Getting better docs is hard as is today.

I like your second option, of embedding version strings in the docs. For
parts we got documents on, the runtime internal
design doesn't change as a pace that is fast enough to be a hassle.

Later we should have as part of our release process record in the mono repo
the docs hash and export the relevant parts to a
per-version archive. That would be great to have.

--
Rodrigo

On Wed, Oct 28, 2015 at 2:21 PM, Andi McClure <andi.mcclure at xamarin.com>
wrote:

> 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 at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-devel-list
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ximian.com/pipermail/mono-devel-list/attachments/20151106/d7eac65e/attachment.html>