search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Map out location of content sources for new docs site #977

Closed mojavelinux closed 2 years ago

mojavelinux commented 3 years ago

In an effort to improve the documentation, the documentation content is being migrated to the Antora structure so it can be managed, built, and published using Antora. The main focus of this migration is to allow the content to be versioned, isolate the docs for the AsciiDoc language so it can be submitted to the AsciiDoc Language project at Eclipse, pull in docs from various subprojects, and to better organize the documentation.

To complete this migration, we need to decide on the location of the content sources. Here's the plan so far:

Asciidoctor

This is the documentation for the Asciidoctor processor itself. It does not include documentation for the core AsciiDoc language. It does include APIs and language extensions that are specific to the Asciidoctor processor.

AsciiDoc

This is the documentation for the AsciiDoc language (as maintained by the Asciidoctor project). It does not include references to the Asciidoctor processor or features specific to it. It documents the language as we know it today and how it is interpreted by the Asciidoctor processor.

Project / Org

This is documentation for the Asciidoctor project / ecosystem as a whole. It only contains general information and policy documents.

docs.asciidoctor.org

This is the playbook / build repository for the docs.asciidoctor.org site.

Other projects

name: asciidoctorj name: asciidoctor.js name: maven-plugin name: intellij-plugin name: pdf-converter name: web-pdf-converter name: diagram-extension name: kroki-extension

Open Questions

ggrossetie commented 3 years ago

Should the docs repositories be named using a docs- prefix or -docs suffix?

Can't explain why but I prefer -docs suffix 😅

What component name pattern should we follow for other projects? Is the asciidoctor- prefix necessary?

I like the names used in the "Other projects" section. I think that the "asciidoctor" prefix is unnecessary on "pdf-converter", "diagram-extension" or "maven-plugin" since we know they are all related to Asciidoctor.

What should we use as the symbolic name for the latest version in the URL? latest or current?

Yes that could be useful 👍🏻

Should we create the repo asciidoctor/asciidoctor-docs with a README that links to asciidoctor/asciidoctor

Not sure what you have in mind but I have no objection.

mojavelinux commented 3 years ago

Thanks for your input!

Can't explain why but I prefer -docs suffix sweat_smile

Yeah! Sarah and I like it too, so let's do it. It feels the most user-friendly since people don't tend to think in postfix notation.

What should we use as the symbolic name for the latest version in the URL? latest or current?

Yes that could be useful

One of the killer new features of Antora 3 ;)

But which name do you prefer, "latest" or "current"?

Should we create the repo asciidoctor/asciidoctor-docs with a README that links to asciidoctor/asciidoctor

Not sure what you have in mind but I have no objection.

In case someone is looking for the docs to contribute, this repo + README would tell them "hey, the docs are in the main repository". That way, it doesn't look like there are no docs ;)

ggrossetie commented 3 years ago

But which name do you prefer, "latest" or "current"?

I prefer "latest" because in my head it reads as "latest and greatest" but Joschi/Yoshi :sauropod: made a good point on Twitter. The term "latest" could be confusing because you can be sure if it includes prereleases or not. In this case, "current" might be a better option.

graphitefriction commented 3 years ago

This is the documentation for the Asciidoctor processor itself. It does not include documentation for the core AsciiDoc language. It does include APIs and language extensions that are specific to the Asciidoctor processor.

The branch currently hosting the Asciidoctor and AsciiDoc docs used by the staging site is going to be removed because we don't want to merge all the AsciiDoc commits into the main branch since AsciiDoc is getting its own repo now. However, there's probably a few chunks of content that are in the Asciidoctor component at the moment that might not belong there, so I'd like to get some feedback/reviews from other people when I submit the PR. Since reading all the raw files in no particular order isn't fun, can we switch the playbook to use the PR branch (once I create it) in my fork so people can review the results of the PR on the staging site? We'd do the same switch for the AsciiDoc component PR.

Sarah will submit a PR with the migrated content using a single commit

Because I've probably moved and renamed every file at least five times now and don't want to torture anyone with that history 😱 I took thrashing to a whole new level 🤣

It [the AsciiDoc component] does not include references to the Asciidoctor processor or features specific to it.

Actually, the PR I'm preparing that is destined for the main branch does have references to the Asciidoctor processors. As well as references to specific processors like Asciidoctor PDF since there are attributes that only apply to specific processors. It will be the initial contribution branch for the specification which will have all references to specific processors removed.

version: latest (or whatever symbolic name we use for the latest version)

This one is hard because I can totally see the logic behind the different options. But, like @Mogztter noted regarding the point Joschi/Yoshi :sauropod: made about "latest" and whether it includes prereleases or not. In the context of a URL like https://docs.asciidoctor.org/asciidoc/latest/blocks/get-started.html, does latest mean last night's snapshot or the latest GA release? Whereas I interpret "current", in the context of a URL https://docs.asciidoctor.org/asciidoc/current/blocks/get-started.html as more ambiguous and therefore more likely to be the newest stable, GA version/what should be used in prod/not last night's snapshot -- I know, it doesn't seem logical 😉

So, I'm leaning towards "current".

displayVersion: latest (or make name clickable in the component drawer)

Just my opinion, but I'm fine with the display version (what's shown in the drawer on the sidebar) being the same as the current/latest/symbolic name in the URL segment when the component has no other versions. So for AsciiDoc the symbolic and version/displayVersion can all be the same.

But, as a user, I hate when software has multiple stable versions but you can't easily identify (in the documentation you're reading) what the actual version number of the current/latest version is 😠. So with Asciidoctor, I'm all for the symbolic current/latest URL segment because that's important for external linking, but I'd prefer the displayVersion to be the number.

branch for production will be main (or latest)

For the AsciiDoc repo branch, I prefer main

mojavelinux commented 3 years ago

@graphitefriction great response!

can we switch the playbook to use the PR branch (once I create it) in my fork so people can review the results of the PR on the staging site?

Absolutely.

It will be the initial contribution branch for the specification which will have all references to specific processors removed.

Exactly. And even that can be clean up after the initial contribution is submitted and going through the initial review process.

does latest mean last night's snapshot or the latest GA release?

This latest vs current is tough because, whichever one we choose, it's possible for someone to see it the other way. Ultimately, I think it has the meaning we give to it.

Throughout the Antora docs, we say over and over that "latest" is the greatest semantic version that is not a prerelease. Thus, by that definition, it's exactly what we want.

I also polled the Twittersphere to see what term people associate with this definition. In that poll, latest was the decisive winner. https://twitter.com/mojavelinux/status/1323543716796096514

So unless there is an exceptionally strong argument for "current", I think we should stick with "latest".

I'm all for the symbolic current/latest URL segment because that's important for external linking, but I'd prefer the displayVersion to be the number.

For Asciidoctor (and Asciidoctor.js), this is still the open question. Do we want the latest version (e.g., 2.0) to redirect to the symbolic name, like Couchbase (https://docs.couchbase.com/server/6.6/introduction/why-couchbase.html), or do we want it the other way around?

mojavelinux commented 3 years ago

Btw, I had considered using asciidoc-lang-docs as the name of the repository for the AsciiDoc docs component, since it is just about the language. But I ultimately decided against it because I feel that will be confusing once the asciidoc-lang project is up and running. The name asciidoc-docs reads more like a precursor, and thus easier understood to be the predecessor to asciidoc-lang the project.

mojavelinux commented 3 years ago

The asciidoc-docs repo is ready for pushes! https://github.com/asciidoctor/asciidoc-docs

abelsromero commented 3 years ago

About the "other projects", do we want to redirect to https://asciidoctor-docs.netlify.app already or do we wait?

mojavelinux commented 3 years ago

We plan to have docs.asciidoctor.org live by the end of the month, so it's best to wait. We don't want to publicize the preview URL too much as it will create confusion, especially this close to the launch.

abelsromero commented 3 years ago

@mojavelinux For the sake of consistency across repos have we considered a writting style guide? For example, things like the use of "you vs we" in tutorials.

mojavelinux commented 3 years ago

Yes, Sarah is working on drafting one (from her experience migrating and rewriting the docs). When we push up the docs for the org (wherever we decide to put them) it will be part of it.

abelsromero commented 3 years ago

Yes, Sarah is working on drafting one (from her experience migrating and rewriting the docs). When we push up the docs for the org (wherever we decide to put them) it will be part of it.

question, is there a draft to check?

mojavelinux commented 2 years ago

I view this issue as resolved. Any follow-ups should be created as separate issues in https://github.com/asciidoctor/docs.asciidoctor.org or the respective content repository.