asciidoc-wg issueshttps://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc-wg/-/issues2022-10-20T17:59:42Zhttps://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc-wg/-/issues/8Create stickers as first step towards swag for AsciiDoc2022-10-20T17:59:42ZAlexander SchwartzCreate stickers as first step towards swag for AsciiDocAs part of the AsciiDoc WG plan for 2022 is to create swag. As a first step it would be nice to have stickers.
Alexander has some experience in preparing logos for printing at Stickermule, and will prepare from the Ura design set the r...As part of the AsciiDoc WG plan for 2022 is to create swag. As a first step it would be nice to have stickers.
Alexander has some experience in preparing logos for printing at Stickermule, and will prepare from the Ura design set the ready-to-print cut-outs, and will do the necessary communication with the Eclipse Foundation.Alexander SchwartzAlexander Schwartzhttps://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc-wg/-/issues/4Develop logo and brand identity guidelines for AsciiDoc2024-03-27T20:06:46ZDan AllenDevelop logo and brand identity guidelines for AsciiDocAsciiDoc has never had an official logo, so we need to create one. This effort should be framed as an initial logo design rather than a redesign. (In other words, please disregard all previous brand identity, or lack thereof). The AsciiD...AsciiDoc has never had an official logo, so we need to create one. This effort should be framed as an initial logo design rather than a redesign. (In other words, please disregard all previous brand identity, or lack thereof). The AsciiDoc Working Group (WG) is responsible for the AsciiDoc brand identity and provides the governance structure to coordinate and manage this effort.
Please note that the development of the AsciiDoc logo is a blocker for the relaunch of asciidoc.org.
*The [AsciiDoc WG](https://asciidoc-wg.eclipse.org) has a [temporary logo](https://www.eclipse.org/org/artwork/#wg-logos). It was created as a placeholder until the AsciiDoc WG at Eclipse was fully formed and had the necessary budget to undertake this initiative. Please disregard the temporary logo when designing the official logo. It's not a reflection of the AsciiDoc brand identity.*
## Design brief
The style we're aiming for is modern, minimalistic, and/or abstract. Among other places, the logo will be prominently featured on the relaunch of the asciidoc.org site. The current asciidoc.org site, which has stood for over two decades, looks very antiquated and is precisely the early dot-com, raw HTML look from which we're aiming to escape.
Shapes we may want to incorporate into the logo are an equals sign (`=`), a dot (`.`), the letter "A", and the letter "D". The equals sign is notable because it's the first character in most AsciiDoc documents and as a marker for section titles. It's also used as an enclosure for example, admonition, and collapsible blocks. The dot is significant because it's the first character of a block title. Since both "A" and "D" are uppercase letters in AsciiDoc, we should avoid using the lowercase version of these letters in the logo as that would be misleading.
We often say that the AsciiDoc language is a form of digital shorthand. So we could play on the concept of shorthand writing in the logo.
## Color
We want AsciiDoc to make a bold statement that it's entering a new era, that it's here to stay, and that it's evolving. Let's get away from anything that looks stale, corporate, or conservative. Where on the spectrum the color falls we leave up to the discretion of the designer, but it should appear bright and lively. Possible ideas are international orange or bright forest green. We'd like to avoid blue and avoid yellow. But we're also open to new ideas that shatter or preconceived notions about color.
The logo should work when shown in all white on a dark background for the purpose of being placed alongside other brand identities (sponsor lists, trade show booths, etc).
## Variants / logo family
The AsciiDoc logo needs to be designed in a way that it can support a logo family (sort of like the [Jakarta EE logo](https://www.eclipse.org/org/artwork/#jakarta-ee-logos)). We know we need to support several variants:
* to represent the language (and AsciiDoc as a whole)
* as a favicon for the asciidoc.org site
* to represent a compatible implementation
* to represent an AsciiDoc file (i.s., filetype) (like you see in from of .md files shown here https://gitlab.eclipse.org/eclipse/chess/chess)
* to represent the working group (perhaps like for https://tangle.ee/, also see on https://www.eclipse.org/org/artwork/#wg-logos)
## Usage and brand identity guidelines
We want these logos to be accompanied by usage and brand identity guidelines. Here are some of the things to consider in those guidelines:
* AsciiDoc is not to be written in all uppercase (wrong: ASCIIDOC)
* AsciiDoc is not to be written with ASCII in uppercase (wrong: ASCIIDoc or ASCIIdoc)
* AsciiDoc is not to be written with a lowercase "d" (wrong: Asciidoc)
* AsciiDoc can be written in all lowercase in code when uppercase is not permitted (correct: asciidoc)
* If the "a" in AsciiDoc is lowercase in code, the "d" should not be uppercase (wrong: asciiDoc)
* AsciiDoc is a registered trademark, so define when the registered trademark symbol is required
We'll iterate until there's general agreement that we're satisfied with the result. Ultimately, the AsciiDoc WG Steering Committee will vote on the design. But that vote will take into account feedback from the AsciiDoc community-at-large.
## Relationship to Asciidoctor logo
The [Asciidoctor project](https://docs.asciidoctor.org), out of which this initiative emerged, has its own logo. That logo could be a source of inspiration, but must remain visually distinct as it represents itself rather than AsciiDoc. One way to draw a distinction is for the AsciiDoc logo to use both the "A" and the "D", contrasting with Asciidoctor's use of only the "A". It also reinforces that the A and D are uppercase in AsciiDoc.
## Contract
We will be using [Ura Design](https://ura.design) as the design firm to develop the logo and brand guidelines.Dan AllenDan Allenhttps://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc-wg/-/issues/3Develop initial content for asciidoc.org2021-12-18T00:41:46ZDan AllenDevelop initial content for asciidoc.orgThis is a companion issue for #1 to track the creation of the content and interactivity for the initial asciidoc.org site. When working on the content, we should assume that, within reason, the design can be updated to accommodate the co...This is a companion issue for #1 to track the creation of the content and interactivity for the initial asciidoc.org site. When working on the content, we should assume that, within reason, the design can be updated to accommodate the content. The content should be both concise and meaningful. We want a visitor to come away with a solid understanding of what AsciiDoc is and its goals, how it relates to other formats, how it is managed, and how the ecosystem is organized.
The in progress content can be found in the following shared document:
https://docs.google.com/document/d/1nflfJyxOZn1hHLZfkX_LrzFiljpRTSEdZZLh_gK4KHI/edit?usp=sharinghttps://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc-wg/-/issues/2Set up repository to manage the source of the asciidoc.org site2021-09-24T18:02:09ZDan AllenSet up repository to manage the source of the asciidoc.org siteThis issue will track the task of getting the repository set up that we can use to host and manage the source of the asciidoc.org site. We also intend to use GitLab Pages to host the site. Using GitLab Pages, or a comparable host, is imp...This issue will track the task of getting the repository set up that we can use to host and manage the source of the asciidoc.org site. We also intend to use GitLab Pages to host the site. Using GitLab Pages, or a comparable host, is important because we have to be able to manage redirects for this site to preserve existing links to pages on asciidoc.org.
The main purpose of the site is to communicate what AsciiDoc is, give visitors a good first impression of the technology, and help visitors navigate around the AsciiDoc ecosystem. In brief, it's a landing page for the AsciiDoc brand. We see the site being used primary to help users launch their evaluation of AsciiDoc or to understand how all the parts of the ecoystem (the AsciiDoc WG, the AsciiDoc Language spec, the AsciiDoc processor implementations, the AsciiDoc tooling, etc.) fit together. It will also feature major adopters of the technology and provide testimonials to inspire confidence. Essentially, the site serves as the AsciiDoc pitch.
The site will drive traffic to the AsciiDoc Language specification effort at the Eclipse Foundation, the Eclipse Austen project, the Asciidoctor project, and other implementations, resources, and extensions.
The project leads will come from the AsciiDoc WG. Initially, those leads will be Dan Allen (mojavelinux), Sarah White (swhitesal), and Amarantha Kulkarni (akulkarnijwo).https://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc-wg/-/issues/1Create design for asciidoc.org2021-12-18T00:41:46ZDan AllenCreate design for asciidoc.orgThe AsciiDoc WG will be taking over ownership and maintenance of asciidoc.org. This transfer entails repurposing the site to provide a new entry point for the AsciiDoc ecosystem. That means creating a new design with new content. We cann...The AsciiDoc WG will be taking over ownership and maintenance of asciidoc.org. This transfer entails repurposing the site to provide a new entry point for the AsciiDoc ecosystem. That means creating a new design with new content. We cannot, nor do we want to, host the existing site's content. That content has already been moved to a new domain at https://asciidoc-py.github.io/. (To be courteous, we may want to provide a small hint for those looking for the old site).
This issue will track to creation of the design for this new site.
## Design brief
The purpose of this site is to pitch AsciiDoc. It should give visitors a strong first impression of AsciiDoc and to help them launch their evaluation. It should answer "What is AsciiDoc?" "What can I use it for?" "Who else is using it?" "How does it compare to alternatives?" and related questions, all at a very high level.
## Requirements
asciidoc.org has been practically unchanged for 20 years and looks extremely dated. So the first impression that we want to leave is that AsciiDoc is a fresh and modern technology, and that it is as active as ever. This website is about building confidence and trust. (Imagine the visitor saying "here's a new tool I've been tasked with using; build my confidence in it"). We want the look of the site to be on par with (if not better than) other markup languages and site generators that are more appealing only because they have a more captivating website. It should be big, bold, and confident. (No Courier!!)
What we have in mind is a design punctuated by splashes of color over a blank background, a thick display font for the hero, and a top-to-bottom progressive reveal of information. In other words, the site should visually be very simple and reveal information in stacked sections as the reader scrolls down the page.
As a general guideline, we don't want the landing page to be too text heavy. In other words, it shouldn't look like a continuous article. Rather, it should break up the information visually so that it can be browsed in very consumable chunks.
If the reader doesn't scroll beyond the fold, the reader should see a) the AsciiDoc logo, b) an introduction to AsciiDoc, and c) key links to get around the AsciiDoc ecosystem (language spec, WG, community, etc).
## General outline
The main message on the site will be to communicate what AsciiDoc is (in as few words as possible) and who it applies to. It should have a big slogan and a slightly longer description. Pull the reader in. We might then have boxes to represent different usage scenarios, like documentation, notes, articles, or books and what can be made from it HTML, PDF, EPUB, slides, man pages.
We then might want a brief glimpse of the high-level structure and features of the AsciiDoc language. This might be a carousel, where each slide shows sample AsciiDoc on the left and the published output on the right. Another idea is an interactive "Try It Now" feature. We are aiming to empower the reader so they think, "wow, I can make that from this!?!" It would then link to a language tutorial that explains how to actually make those things.
We then might want a section to introduce the AsciiDoc WG and specification. The idea of this section is to make it clear that the development of the AsciiDoc language is supported by the AsciiDoc WG at the Eclipse Foundation and defined by the specification. This will give the reader a lot of confidence that this language is professional and fit for the enterprise. We don't want this section to be too detailed since the AsciiDoc WG has its own site. We just want to make the association clear.
We then might want a section that explains that you need a processor to convert AsciiDoc to a publishable format and/or a text editor / IDE to write docs with it. And here we would present a list of software that is recognized by the AsciiDoc WG as being on the standards track. We should emphasize that regardless of implementation or editor you choose, there's only one AsciiDoc. However, AsciiDoc can be extended using well-defined extension points, so you may find that some implementations provide access to more extended syntax than others.
Finally, we want to make it clear that AsciiDoc is an ecosystem with an abundance of tools, integrations, services, and add-ons, so there's much more to explore. So we want imagery that gives the impression of something organic, living, and growing.
## Relationship to other sites
Since we will have multiple websites (asciidoc.org, asciidoc-wg.eclipse.org, and possibly asciidoc-lang.org), first and foremost, we need to make it clear that they're all part of the same family. We don't want visitors to think they're competing. They're complimentary. The division is really about the audience we are targeting. **asciidoc.org** is for people who want to learn about and adopt AsciiDoc. It has an onboarding focus. **asciidoc-wg.eclipse.org** is all about maintaining the AsciiDoc language. It looks for ways to meet the needs of writers and organizations using AsciiDoc, and draws in new members. **asciidoc-lang.org** will provide both the definition of the AsciiDoc language (in the form of the spec) and information for processor implementations that are compliant with it (the TCK).
Cross links are certainly important. We may not need a common navbar as each site has such a vastly different focus. But we probably want some consistent interaction model to switch between the sites, and certainly a footer that shares commonalities. We also don't want to have conflicting content, like an introductory tutorial, on more than one site. We need to pick which site does which task and make sure they don't overlap.