doohoyi/chatty-pub
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doc updates

Browse source
This commit is contained in:
Heerko 2021-07-13 17:47:51 +02:00
parent c8d1e2672e
commit 84c26ae60f
2 changed files with 80 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
front/docs/CSS.md
View file

@ -2,11 +2,13 @@
In this document we take a look at what CSS is and how it can be applied to a publication in **Chatty-pub**.
- [What is CSS](#css)
- [What is CSS](#what-is-css)
- [Rules](#rules)
- [Css in chatty-pub](#chatty-pub)
- [Css in chatty-pub](#css-in-chatty-pub)
- [Print settings](#print-settings)
- [Typing Emoji](#emoji)
- [Typing Emoji](#typing-emoji)
---
## What is CSS?
@ -20,6 +22,8 @@ But what HTML does not do is speficy how these elements should look. That is whe
CSS can be used for very basic document text styling — for example changing the color and size of headings and links. It can be used to create layout — for example turning a single column of text into a layout with a main content area and a sidebar for related information. It can even be used for effects such as animation.
In Chatty-pub we're mostly interested in the first part.
---
## Rules
#### _Elements and Classes_
@ -79,6 +83,8 @@ In the `h1` example above, we set the following property: `font-size: 20px;`. Th
[More information on units](https://www.w3.org/Style/Examples/007/units.en.html).
---
## CSS in Chatty-pub
When you react to a message in Zulip with an emoji, this emoji gets turned into a class in **Chatty-pub**. So lets say you responded to a message with the strawberry 🍓 emoji. In **Chatty-Pub** the message will have class with that emoji as selector. (You can confirm this by rolling over the message, the emoji should popup on a overlay.) So now to style that message, you go to the #rules channel and add a message with the following content:
@ -128,6 +134,8 @@ It is possible to bypass the parser and add arbitrary code to the CSS on the pag
```
</code>
---
## Print settings
To set the paper size we can use the special selector `@page`. The following snippet set the page size to A5.
@ -138,7 +146,7 @@ To set the paper size we can use the special selector `@page`. The following sni
}
```
Regrettably browser support for `@page` is [spotty](https://caniuse.com/css-paged-media). You will get the best results using Google Chrome.
Regrettably [browser support](https://caniuse.com/css-paged-media) for `@page` is spotty. Currently only Google Chrome will allow you to set page sizes etc.
[Pagedmedia.org](https://www.pagedmedia.org/pagedjs-sneak-peeks/) has an excellent explanation on using `@page`. The [Paged media module](https://developer.mozilla.org/en-US/docs/Web/CSS/Paged_Media) at Mozilla also.
@ -173,7 +181,33 @@ A colors value can defined in multiple ways:
### Fonts
- TBD/Todo
- [font-family](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) - The font-family CSS property specifies a prioritized list of one or more font family names and/or generic family names for the selected element.
You can choose one of the following generic fonts. Which exact font will be used is dependant on your computers' settings.
```css
font-family: serif;
font-family: sans-serif;
font-family: monospace;
font-family: cursive;
font-family: fantasy;
```
It is also possible to specify an exact font name, but it will only be used if it is actually available on your system.
For example following statement will try to use Helvetica if available, but will fallback on a generic sans-serif font if not.
```css
font-family: "Helvetica Neue", sans-serif;
```
(Note the quotes around the font name)
We have not yet implemented a way to upload and use fonts. Working on it!
- [font-size](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size) - The font-size CSS property sets the size of the font. Changing the font size also updates the sizes of the font size-relative <length> units, such as em, ex, and so forth.
- [font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) - The font-style CSS property sets whether a font should be styled with a normal, italic, or oblique face from its font-family.
- [font-weigh](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight) - The font-weight CSS property sets the weight (or boldness) of the font. The weights available depend on the font-family that is currently set.
- [line-height](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height) - The line-height CSS property sets the height of a line box. It's commonly used to set the distance between lines of text.
### Text

74
front/docs/Workshop.md
View file

@ -2,25 +2,25 @@
## Introduction
ChattyPub is a design tool in the making – leveraging a chat interface to apply styles and formats to the content of a publication.
ChattyPub is a design tool in the making – leveraging a chat interface to apply styles and formats to the content of a publication.
The workshop will explore in a practical manner how the process of co-designing a publication can unfold, specifically when several people are working at the same time using a chat interface as the main design tool. During HDSA2021 we would like to open up the process of making this tool and explore together its possibilities and limitations. The workshop will take place towards the end of the one-week summer academy program. Thus, we will be able to use some of the documentation produced during the week — workshops scripts, prototypes, game cards, recipes, ... as well as conversations we will have on different platforms – synchronously and asynchronously.
The workshop will explore in a practical manner how the process of co-designing a publication can unfold, specifically when several people are working at the same time using a chat interface as the main design tool. During HDSA2021 we would like to open up the process of making this tool and explore together its possibilities and limitations. The workshop will take place towards the end of the one-week summer academy program. Thus, we will be able to use some of the documentation produced during the week — workshops scripts, prototypes, game cards, recipes, ... as well as conversations we will have on different platforms – synchronously and asynchronously.
Commands allow you to style the texts and images, but someone else can change their appearance again later! How will we negotiate these design decisions synchronously and asynchronously? The outcome could be a zine, posters or a webpage.
This script aims to provide the necessary instructions to host a workshop around ChattyPub that can accomodate different skills and knowledges in different contexts.
This script aims to provide the necessary instructions to host a workshop around ChattyPub that can accomodate different skills and knowledges in different contexts.
## Goals
- Learn to collaboratively write, design, and print documents using ChattyPub
- Produce publications of / relating to HDSA2021 (documentation, prototypes, conversations, etc...)
- Learn and/or practice styling with CSS & Emojis
## Requirements
- a computer, web-browser, and connection to the internet
- an account for the Hackers & Designers Zulip instance: https://chat.hackersanddesigners.nl/
- a printer
- a computer, web-browser, and connection to the internet
- an account for the Hackers & Designers Zulip instance: https://chat.hackersanddesigners.nl/
- a printer
## Preparation
@ -28,11 +28,12 @@ Before the summer academy: Most important is for all workshop participants to se
On the first day of the summer academy (monday): Participants are introduced to the Zulip interface and instructed to use it for communication during the course of the week. Zulip makes use of a rather unconventional (but powerful) chat-threading logic, so it would be good to spend some time interacting with it and settle into this new environment.
Workshop hosts and participants are encouraged to think about how they would like to document their processes during the summer academy. What is included and what isn't? How is this shared? Is there a regular moment during the day dedicated to documentation or is it more ad-hoc? We suggest using Etherpad for collaborative note taking, and regularly making screenshots or screenrecordings and photos. We have previously compiled a so-called "tool-ecology", a list of tools we have good experiences with and recommend using during the summer academy: https://etherpad.hackersanddesigners.nl/p/hdsa2021-tool-ecology.
Workshop hosts and participants are encouraged to think about how they would like to document their processes during the summer academy. What is included and what isn't? How is this shared? Is there a regular moment during the day dedicated to documentation or is it more ad-hoc? We suggest using Etherpad for collaborative note taking, and regularly making screenshots or screenrecordings and photos. We have previously compiled a so-called "tool-ecology", a list of tools we have good experiences with and recommend using during the summer academy: https://etherpad.hackersanddesigners.nl/p/hdsa2021-tool-ecology.
Texts, notes, chats, images, and screenshots will make great material for our workshop.
## How It Works
### Zulip
On Zulip, conversations are categorized into different "Streams", which are comparable to "channels" in other messaging services like Discord. Streams can be public or private and host conversations consisting of text, images, files, reactions, etc..
@ -42,6 +43,7 @@ What differentiates Zulip from most messaging platforms is the way streams are s
Zulip allows you to react to messages using emoji's as well. We will make heavy use of emojis during this workshop.
There are several ways to engage with Zulip, including a web-client, a desktop app, and a mobile app.
### ChattyPub
http://chattypub.hackersanddesigners.nl
@ -49,22 +51,23 @@ http://chattypub.hackersanddesigners.nl
ChattyPub is a website that acts as a different interface to the same Zulip service. ChattyPub takes a stream from Zulip, combines messages into long-form articles and uses a design system combining Emojis and CSS syntax to style the messages, effectively turning the stream into a (printable!) webpage.
## Making a publication with Zulip & ChattyPub
### Content
1. Create a stream on Zulip
- Ensure that the stream name starts with `pub-`.
- Ensure that the stream is public.
- Ensure that the stream name starts with `pub-`.
- Ensure that the stream is public.
2. Go to [ChattyPub](https://chattypub.hackersanddesigners.nl). The stream you created will be visible on the left-side navigation.
3. Click on your stream.
4. The main (middle) section of the website will have:
- Your stream name (which will be the name of your publication)
- The topics of your stream (which will act as "Chapters" in your publication)
- Topics are collapsed by default, click the expand button next to a topic to display it's messages as an article.
- Your stream name (which will be the name of your publication)
- The topics of your stream (which will act as "Chapters" in your publication)
- Topics are collapsed by default, click the expand button next to a topic to display it's messages as an article.
5. To create a new topic (chapter), return to Zulip and type a message to your stream, making sure to send it to the topic you want to create.
### Rules
The right-hand side of the ChattyPub interface is reserved for one topic in your stream: "rules". This topic will house definitions for styles you want to apply to messages in your stream.
The right-hand side of the ChattyPub interface is reserved for one topic in your stream: "rules". This topic will house definitions for styles you want to apply to messages in your stream.
Go back to Zulip and create the topic in your stream called "rules".
@ -76,12 +79,15 @@ Every message you send to this topic should consist of a single emoji followed b
text-decoration: underline;
}
```
These messages should be unique and follow the CSS syntax, as described in the [introduction to CSS](https://github.com/hackersanddesigners/chatty-pub/blob/master/front/docs/CSS.md). If you are comfortable with CSS, you can skip to the part of the document that describes [how CSS is used in ChattyPub](https://github.com/hackersanddesigners/chatty-pub/blob/master/front/docs/CSS.md#css-in-chatty-pub).
To apply these styles to the contents of your publication, head back to any other topic in your stream, select a message you'd like to style, and react to it with the emoji whose styles you want to apply. On ChattyPub, the message should be rendered with these styles.
If you'd like to style only a part of a message, select the message in Zulip and quote and respond to it (in the 3-dot menu). This will produce a text in your input box on the bottom of the interface. Delete the parts of the quoted message that you don't want the styles applied to, and send your response. When you react with an emoji to your own response, the part of the message you quoted will inherit the styles defined for that emoji.
Keep in mind that you can edit your own messages! So if you make a mistake (forgetting the semi-colon at the end of a statement is a common one), roll over your message and click the little pen at the top righthand side of the message.
### Printing
TBD
@ -91,28 +97,30 @@ TBD
The workshop is split over two sessions (over two days) of 4 hours each.
_Opening Session: Introductions & first encounters with ChattyPub_
- Introductory presentation ( 1hr ) -- will be livestreamed in the morning / recorded and shared afterwards.
- Context and background on H&D's publishing activities (Anja & Juliette)
- Introduction to ChattyPub (Karl).
- Introduction to CSS (Heerko).
- How it all comes together (emojis ;])(Karl)
- Experimenting with ChattyPub! ( 2 hrs ) [How are people going to do this asynchronously? it needs maybe more direction and steps from here]+1
- all levels of technical knowledge should be accommodated
- general knowledge and detailed instructions about CSS can be found [here](https://github.com/hackersanddesigners/chatty-pub/blob/master/front/docs/CSS.md)
- it's reccommended to group together participants with different levels of experience with CSS
- Introductory presentation ( 1hr ) -- will be livestreamed in the morning / recorded and shared afterwards.
- Context and background on H&D's publishing activities (Anja & Juliette)
- Introduction to ChattyPub (Karl).
- Introduction to CSS (Heerko).
- How it all comes together (emojis ;])(Karl)
- Experimenting with ChattyPub! ( 2 hrs ) [How are people going to do this asynchronously? it needs maybe more direction and steps from here]+1
- all levels of technical knowledge should be accommodated
- general knowledge and detailed instructions about CSS can be found [here](https://github.com/hackersanddesigners/chatty-pub/blob/master/front/docs/CSS.md)
- it's reccommended to group together participants with different levels of experience with CSS
- Brainstorm Session (1 hr) [also for the brainstorm it would be nice to add some suggestions for how to do this if you are not in Amsterdam and maybe not even togeter in a room.]
- in groups of 2-3, participants brainstorm publications they will make during the main session [Is this brainstorm about content? or about the negotiation process for the layout? can we come up with a format for the brainstorm or some questions as an aid?]
- If you are planning to print your publication, take into account the printing limitations of your home printer or local print shop [take into account in what way? regarding the format? will i need to adjust something in the css? or in regards to bw/color? ]
- in groups of 2-3, participants brainstorm publications they will make during the main session [Is this brainstorm about content? or about the negotiation process for the layout? can we come up with a format for the brainstorm or some questions as an aid?]
- If you are planning to print your publication, take into account the printing limitations of your home printer or local print shop [take into account in what way? regarding the format? will i need to adjust something in the css? or in regards to bw/color? ]
_Main Session: Chat => Print_
- Making publications ( 2 hrs )
- Groups work on the publications planned in the previous session [how? will there be channels prepared? are people making their own channels?]
- Organizers are available to help where needed [who are the organizers? in vienna and pittsburgh people will be online on their own.. how do they prepare for that?]
- Groups work on the publications planned in the previous session [how? will there be channels prepared? are people making their own channels?]
- Organizers are available to help where needed [who are the organizers? in vienna and pittsburgh people will be online on their own.. how do they prepare for that?]
- Printing Publications ( 1 hr )
- A printer is required in the space (or easily accessible)
- Accommodating for different paper sizes is an added bonus
- Binding could be fun too
- A printer is required in the space (or easily accessible)
- Accommodating for different paper sizes is an added bonus
- Binding could be fun too
- Sharing outcomes and reflections ( 1 hr ) [add link and time in different time zones]
- Round of publications
- Reflection on process
- Feedback on ChattyPub
- Round of publications
- Reflection on process
- Feedback on ChattyPub