The Ur Project

Documenting the craft of stacking things so they remain stacked. For a very long time.

Documentation portal

I've been spending my time writing out the documentation that needs to be in place on day #1. This is relatively important because (hopefully) there will be a lot of people showing up that want to try out the features of the OS. Most importantly, I said upfront that we're making a system that will allow anyone to build out a serious Linux Distro, so that part should really be in place at launch, too.

I can prove that it is by publishing a "how to make your own distro" guide. Certainly, that also means that people need to understand how pkg works and how to even install onto a system for the first time as well. Hence, the minimum set of user manuals needs to be:

It's all in good shape

And I don't mean the documentation. I mean the features that make this possible: The installer is getting some last minute testing to make sure that the recent key/signing changes didn't break anything (it did). The package management is working well (it didn't break) and the build system is easy to deploy and operate (so far, that's going good).

I'm starting to build out the documentation website. It will, at one point, have copies of all the documentation, all the useful user guides, API references and manual pages. While that's being built out, I'm focusing on adding at least one major user guide document every day.

I'm writing these documents all in markdown. I like markdown, despite it being a silly markup format. But there's good reasons to use markdown. Many projects already use, and used, markdown as a way to write manual pages. Instead of something like roff or rst, markdown is simple enough that it just works. There's several markdown to man page converters, too, so all the Ur Project components use markdown for literally every piece of documentation.

What's already in place

There's the overview page at Docs that lists everything already. It does link to a bunch of pages that will say "placeholder, content coming" for the time being.

User Guides has a completed Installation guide, a Basic system maintenance guide that explains the basics of working with the pkg tool. There is a Verifying the Sandcastle signatures guide for those that need, or want, to verify signatures.

There is a section Manual Pages that will contain all the manual pages from the project's source code, including boot-manager and others.

There's also a Developer Documentation section where there will be a place to put all the API docs. Things like the recipe format will be explained in depth over here, as well as all the various API's to talk to dispatcher and designer and use MCPs.

If you're interested in helping out, there's a lot that can be done here - certainly any of the guides can benefit from a review, but also they could use screenshots, or even video guides.

--sofar (aka Auke)