Architecture of Consoles: the source of a hardware writing project

A publishing workspace, not a code project

The Architecture of Consoles repository holds the articles that make up the Architecture of Consoles series. The README states the reason it is public, and the reason is not that the software needed to be open source.

It has been made public to enable interested readers to discuss improvements, add translations and possibly more. In other words, the code is not the point, the text is, and the repository is the mechanism by which a reader can influence the text.

The repository has a small and legible layout. The `articles` folder holds the writings, the `resources` folder holds a list of strings that are referenced across the site, and the root carries `STYLES.md`, `TRANSLATIONS.md`, `LICENSE.md`, a `crowdin.yml` and the `.github/` directory. The primary language is not reported, because there is no code in the project, and the topics are correspondingly about content: architecture, articles, computer architecture, console, cpu, discussion, gpu, translation and videogame.

The published site is at `copetti.org/writings/consoles/`, and the README links both the project page and the index of consoles page to `copetti.org/projects/consoles/`. The licence is CC-BY-4.0, which is the right one for this kind of corpus, since the articles are meant to be read, quoted and reused with attribution.

For a site that reviews open source projects, this is an unusual subject, and the interesting question is not what the articles say but how the project is arranged to let other people change them.

One file per console, and an index that is also a file

The structure of the `articles` folder is the design decision of the project, and it is a simple one: each file corresponds to a specific console, except `_index`, which corresponds to the index of consoles page.

That single exception carries the whole hierarchy. The console articles are siblings, not nested, and the page that ties them together is a peer of them rather than a container. A reader looking for one console opens one file, and the index is just another file that lists the others.

The format is Pandoc Markdown, and the files carry some front-matter, mainly meta-data, along with R snippets. The metadata is what turns a plain document into a page with a title, a date and a place in the site, and the R snippets mean the articles are not only prose: they can carry computation, which is the mechanism for anything in the series that is derived rather than asserted.

The README does not document the build process, and it does not need to. The site is built elsewhere, the repository holds the sources, and a contributor follows the conventions in `STYLES.md` rather than running a toolchain. That is a deliberate division: the writing style guide is in the repository, the publishing pipeline is not.

The `resources` folder has a different job. It contains a list of strings that are referenced across the site, and they are isolated for translation purposes, which is the subject of the next section.

resources/ exists so that shared strings can be translated

The `resources` folder is the one piece of structure that exists for a reason other than writing, and it is worth understanding, because it is a pattern that any multi-language documentation project ends up reinventing.

It holds a list of strings that are referenced across the site. Isolating them means the same word, or the same label, or the same piece of interface vocabulary, is defined once and reused, rather than being typed into each article where it would then have to be translated once per article.

The reason this matters is scale. A series about console architecture has many articles, and a great deal of vocabulary is shared between them, the names of the components, the labels used in the diagrams, the recurring phrases. If that vocabulary lives in the prose, a translator has to find every occurrence, and a correction to a term has to be made in every place it appears, and the two jobs get confused with each other.

The Crowdin configuration at the root, `crowdin.yml`, is what acts on that separation. The resources are the translatable units, and the localisations are produced from them, with the articles around them staying in one language at a time.

The invitation to translate is in the README as well, and the reasoning given is traffic. With all the traffic that has been going on the website, the author saw it as an opportunity to enable readers from anywhere in the world to help translate the content, helping it reach the widest audience. The process itself is in `TRANSLATIONS.md`, which the README links as the translation button in the badge row and as the document to check out if translating is something you are interested in.

Corrections start as an issue, deliberately

The contribution policy in this repository is unusual enough to quote, and it is not an accident of wording.

The README asks that if you think there is a mistake, whether a technicality or something that involves multiple lines of text, you open an issue so it can be discussed. It then says it does not recommend submitting a pull request right away, since there may be a disagreement and the author does not want the reader to waste their time, but is very open to any discussion.

That is a policy for a corpus of prose rather than for a codebase. In code, a pull request that is wrong is still a reviewable artefact, and the cost of a rejected pull request is mostly the reviewer's time. In a long article about the architecture of a specific console, a rewrite can run to a great deal of prose, and disagreeing about the argument after the fact is expensive for both sides. Opening an issue first means the disagreement, if there is one, costs a paragraph.

The badge row in the README reinforces the tone. Alongside the licence badge there are two buttons, one for the stylesheet and one for translations, both pointing at documents in the repository rather than at external sites, which is a small signal that the repository is the place where the project explains itself.

`STYLES.md` is the style guide, and it is a real document rather than a link to a website. That matters for a series with a house voice: the technical articles have a consistent way of presenting a block diagram, a specification table and a comparison, and that consistency is what makes a series readable as a series.

Where this repository is the wrong tool

Two things are worth saying plainly about a project like this one.

The first is that there is nothing to run. There is no build output, no library, no service and no test suite in the usual sense. A reader who clones the repository gets Markdown, a style guide and a translation guide, and a workflow to publish a website. For an engineer evaluating what to adopt, the useful question is therefore not what it does but whether the writing is worth reading, and that is a question the published site answers better than the repository does.

The second is the maintenance shape. The articles describe hardware that is fixed in the past, which is an advantage, because the subject does not change, but it also means the value of the project is concentrated in its accuracy. A wrong statement about a console's memory bus does not become less wrong as the site gets traffic, and the correction path, an issue followed by a discussion followed by a pull request, is deliberately slow. The author says as much when they say a pull request straight away is not recommended.

The alternative for a reader who wants the knowledge in another form is the published site, with its own navigation and its own search, which is the artefact most people will actually use. For a reader who wants to reuse the text, the licence is the deciding factor: CC-BY-4.0 permits reuse with attribution, so a course, a translation or a book chapter can build on these articles as long as the author is credited, and the repository makes the attribution easy to get right because the licence and the style guide are both in it.

One more practical point applies to anyone who contributes: the repository asks for discussion before a pull request, so the first step is an issue, and the `articles` folder with one file per console is the place a change will land.

Editorial conclusion

The Architecture of Consoles repository fits a reader who wants to correct a technical statement in a console architecture article, a translator who wants the series in their own language, and a teacher who wants the source of the articles rather than a PDF. It is the wrong tool for anyone looking for an executable artefact, because there is nothing in it to run, and it is the wrong place to look for the rendered version, since the published site is the product and the repository is its source. Before contributing, read `STYLES.md` for the house conventions and `TRANSLATIONS.md` for the translation workflow, and remember that the licence is CC-BY-4.0, so anything you reuse needs attribution and a link back.

Frequently asked questions

Official sources

1. flipacholas/Architecture-of-consoles on GitHub
2. Issues
3. License: CC-BY-4.0
4. Project website
5. README