Forem: Milan Zivkovic

Path to better README.md through Markdown syntax

Milan Zivkovic — Sun, 12 Dec 2021 21:48:55 +0000

Intro

As my journey at FlatIron school comes to a final phase and having a few projects built, I look back and I see a common thing in all of them: bad readme files! Now when I go back to my first CLI I am having hard time starting it without diving into code files. Idea of writing this blog is to serve as reference and help for Markdown syntax used to write README files.

What you will find in this blog

About README
About Markdown
Useful VS Code extensions
Markdown syntax (links, headings, tables, code snippets)
References

README

README is a text file used to describe the creators idea behind the application, the problem they are trying to solve, a way to intrigue possible users, help them with installation and usage, and leave them a place where they can point to some bugs or possible improvements of application.
The most common language used for writing README is Markdown.

Markdown

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.Markdown is platform independent. You can create Markdown-formatted text on any device running any operating system. There are several online Markdown editors that you can use to try writing in Markdown. Dillinger is one of the best online Markdown editors.

VS Code extensions

Adding extensions to VS code setup can be of great use if you choose right ones. In your VS Code window open extensions(shift+command+X for Mac or shift+command+X for windows) and find ones you need through search bar.

In the search bar type Markdown and you will see plenty of extensions for Markdown language.
Markdown All in One
This is the one I use most often.
This extension will give you keyboard shortcuts, a table of content, and best of all auto preview. Make sure to scroll down and check out their animations and notes how to best utilize this extension.
Markdown Theme Kit
I use this one to set difference for code snippets as it can set themes which will look not only good but also emphasize importance of code snippets you add in README.md file.
Other useful extensions: markdownlint, Markdown Emoji

Markdown syntax

Comments

<!-- this is comment-->

Headings
Similar to HTML, Markdown has different headings which should be used for different importance and not as styling.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Italic, Bold, Strikethrough

_this text is italic_
*this is also italic*
__this text is bold__
**this is also bold**
~~this text~~ is strikethrough

Horizontal rule
Three hyphens or three underscores in line, no spaces.

---
___

Unordered list

- Item 1
- Item 2
 - nested Item 1
 - nested Item 2

Ordered list

1. Item 1
1. Item 2
1. Item 3

External links
In square brackets we will write what we want to be shown on README.md as hyperlink and in parentheses will be the link where it will re-direct us. Extra attribute can be placed after link in parentheses separated with white space and quotations. This will appear when we hover over our link.

[link](https://something/something/... "resources")

Same page links
This is very useful for Table of content part of REDAME.md so the user can easily navigate through file. Square brackets content will appear as link and in parentheses after it (no spaces) we will have # and heading exactly as it is in file. For multi word headings use hyphen to connect the words.

1. [<Heading that will appear as link>](#heading-in-your-file)
2. [How to install](#how-to-install)

Images
Images of file structure, database diagram, or else will make your README.md better and easier for user to understand, navigate, use, and install your application.

![<alt tag>](<image link>)
![cute cat](https://cats/one/...)

Inline code blocks
Open with single backtick and close with same, all in one line.

`<p>this is paragraph</p>`

Multi line code blocks
Open/close with three backticks(no spaces between) with possible additional 'attribute' where we can specify in what language code snippet is written in. Different languages will have different highlighting.

` ` ` javascript
const myFunction = (){
   console.log('Hello World')
}
 ` ` `

Tables

|first name|last name|email|
|----------|---------|-----|
|John| Do|jd@example.com|

Task List
Task lists can be used for part of README.md reserved for listings of future upgrades. We can check them out as we go.

- [x] Task 1
- [ ] Task 2
- [X] Task 3

Summary

Probably the first file someone will see when they come to your application is README.md, this is the right place to hook them to stay and dive into your application.
README.md in your application is about presenting your product (and yourself) with 'user manual', recipe, idea behind it and much more and Markdown give us power not to stress about 'how' so we can focus on 'what' to write. Plain text is good but utilizing Markdown's features will make our README.md more appealing and easier to understand.

References

About README.md
Traversy media about Markdown
About markdown
Dillinger- online markdown editor

Database setup and associations for simple quiz app

Milan Zivkovic — Mon, 11 Oct 2021 06:05:53 +0000

Intro

Building a simple quiz application started with a blank diagram and cognition that my SQL knowledge is fading (if I ever had any). I'll just say that I had to refresh on lectures on join tables (inner join tables to be precise).

What you will find in this blog

Here you will find the database diagram and model associations. I hope it will give you guidance for your quiz application. Worth mentioning is that backend side was created in Rails with --api flag (generators will not create views folder, frontend side will be written separately )

Models

Quiz
Question
Option
User
Take
Response

Model Associations

Quiz

has_many :questions
has_many :takes
has_many :users, through: :takes

Question

belongs_to :quiz
has_many :options
has_many :responses

Option

belongs_to :question
has_many :responses

User (with basic validations)

has_many :takes
has_many :quizzes, through: :takes
validates :username, presence: true
validates :email, presence: true
validates :email, uniqueness: true

Take

belongs_to :user
belongs_to :quiz
has_many :responses, dependent: :destroy

Response

belongs_to :take
belongs_to :option
belongs_to :question

Summary

Having Takes table as a join table between Users and Quizzes will give as an option that user can retake the quiz as many times as he/she wants.
Each response will belong to take, question and option. Here we can distinguish responses for the same question with the same option selected but that happens it different takes.

Before sessions and cookies: HTTP request and response

Milan Zivkovic — Fri, 13 Aug 2021 03:04:55 +0000

INTRO

Rails authentication is all about sessions and cookies. But before that I needed little refresh on HTTP requests and responses. It all sounded familiar but I wanted to have it all in one place as a reference when (not if) I need it.

Finding HTTP requests/responses

It's always good to see what are we talking about. Please see instructions hot to see HTTP requests/responses for Chrome browser:
*Navigate to page (anyone you like)
*Right click and hit 'Inspect'
*Select 'Network'
*Select any HTTP request on left side (panel named 'name') and headers will be displayed on right side

HTTP(Hypertext Transfer Protocol) request

HTTP request is a message that one computer sends to another using the HTTP protocol. It’s made by a client of ours API to our API.

Structure:

1. The Request line of the HTTP protocol (has three parts):
Example 1. GET /books HTTP/1.1
Example 2. POST /form.html HTTP/1.1

1.1 HTTP Method- indicate what kind of action our client wants to perform
GET- user wants to “read” a resource (example 1.)
POST- user wants to send us something (example 2.)

1.2 URI of request- refers to the address where the resource is located
Example 1. The user wants to “read”(GET) resources located at /books
Example 2. The user wants to send(POST) something (form.html), we will find this in the body of the HTTP request

1.3 HTTP protocol- there are several versions of HTTP (example HTTP/1.1)

2. The headers of the HTTP request are metadata that are sent in requests to provide information about the request.
Each header is specified with a name, then two points, and then followed by the value of that header. The header can be composed of several individual headers.

metadata in HTTP request- when we retrieve page the server sends with it various bits of information about the thing you are retrieving (metadata).
metadata in general- data that provide information about other data. Metadata summarizes basic information about data, making finding and working with particular instances of data easier.

3. The body of HTTP request place where we put additional information we want is going to send to the server. We can put whatever we want in the body of the request. The body represents (in many cases) content that we want to transmit.
GET requests do not use a body since it’s not sending many complex data when reading information. In the case of the POST method, we use the body of the request to send data to the server (sign in forms for example).

HTTP Response

Structure:

1. Status line
The request status is indicated in the response status line. If there are errors, if it was successful or if it is required some additional actions.
Read more about HTTP status code.

2. The response header
Is set of one or many headers (just like in HTTP request)

3. The body of the response
This part is optional, used when the server wants to transmit data to the user (for a web page it would be HTML (hypertext markup language) document)

sources:
HTTP headers, meta elements and language information
Anatomy of an HTTP request
about metadata
how to see HTTP headers

User authentification and validation for Sinatra project

Milan Zivkovic — Mon, 05 Apr 2021 00:45:23 +0000

Here I would like to share the process of building user authentication and validation in my Sinatra project as well as share resources I found helpful on this subject.

Sinatra project for phase two of Flatiron boot camp among other functionality should be able to keep track of whoever uses our web application, keep track of it, refuse user without proper username and password, and unable certain parts depending on the current user.

Building model for our User

(in this project it will be Dispatcher)

‘./models/dispatcher.rb’

Validations on the model:

Main attributes of class Dispatcher: username, passwords, and email must be passed when we are creating one. Also, they need to be unique and for email, a certain format must be followed.

Creating migration

for our Dispatcher class

'./schema.rb'

Session and cookies

Requests come to our Sinatra app through HTTP which is a stateless protocol, each request is treated as an independent transaction that is unable to use information from any previous requests. This means our app will never be able to keep track of requests and responses. The only thing it will do is to match requests sent from browser with the right route in our ApplicationController. And this can be a problem since we don't want to have everything open for every user. This is where sessions come in handy, to keep track of users, through session objects.
The first step to do this is to enable sessions in our ApplicationController:

Now session object is available to us in every route of our Application through cookies. Sessions and cookies go hand in hand. Sessions as cookies are hash-like objects that store data. Sessions on the server-side and cookies on the user side (in browser). The client-side cookie data will be compared to the server-side session data to help the application what step to take.

Sign up

Before we use a session our dispatcher needs to sign up or log in to our application. This will come as a request that will be matched with the route in our ApplicationController.

Here you can see the logged_in helper method but we will get to them later. Next, we will create an instance of a Dispatcher class based on the params hash our ApplicationController received via post request. And finally, we will use 'id' of that instance created to store it in session hash to keep track of the current user in our app.

This is what the session would look like and how we can authenticate our current user:

Log in

On the log-in route, we will do something different. Instead of creating a new instance, we would need to find one by username and if one is found we will need to check if the password in params matches one stored in our database.

Helper methods

We were using helpers methods to check if anyone logged in and to see who is our current user.

logged_in will give us the boolean value of session[:user_id]. Remember that falsy values in Ruby are 'nil' and 'false' all others are truthy (even empty arrays or strings). Therefore if no one is logged in we wouldn't set session[:user_id].

session[:user_id]=@something.id
#=> nil
!session[:user_id]=@something.id
#=> true
!!session[:user_id]=@something.id
#=> false
if someone is logged in:
!!session[:user_id]=@something.id
#=> true
current_user will use find_by method to match 'id' any instance of Dispatcher object with session[:user_id]
If current_user is true it will return found instance which we can later use to grant or denied access from certain parts of our application.

Clearing sessions

Log out from our application will be done by clearing sessions or setting session[:user_id] to nil.

Our application (session) is ready for new users to be logged in.

Phase_one, CLI project

Milan Zivkovic — Sat, 06 Feb 2021 22:37:54 +0000

Phase One in my Software engineering course at Flatiron is coming to an end. The final two weeks are scheduled for building the CLI project. To be perfectly honest I was behind with lessons and labs and project weeks started for me with two labs left undone. Luckily our cohort leader was very encouraging and point me in the right direction and that I can go back and finish those labs later on.

Missing my group lectures meant there was a lot of reading and watching to do. Search for free Apis' with no key required was a bit harder than I thought at first but again, our cohort leader helped us on this matter too. Finally, I got one that looked usable to me, Repl was the next stop. I was going through Api to see what info I could use for my project and how hard (complicated) would it be to extract the info I might need.
After the init-Repl phase, I had a list of all keys I could use in every object build from Api. Now it was time to make a story of my command-line interfaces (CLI) and this was where I made more than one misstep. Thinking that it would be too simple for my application to do "just that" I overcomplicated it which put me on a sidetrack and cost me a whole evening of work.

Story of my Cli application:

Welcome our new user, and offer him to take a look at our beer selection.
Ask the user would he/she like to know more about any beer from our list (here we would offer the option to "exit" the app).
If he chooses to know more about a certain beer we would confirm that we "heard" right and output a short description about the beer he desired.
We would offer him all other information about his/her selection if the user wishes to know more or to go back to the beer list.
Steps 3. and 4. could be repeated as many time user would like.
At the end before the user leaves our application we would output all his selections and greet him on the way out.

Application buildup

Test ground - Cli application would be built around 3 classes. Api class - would be responsible to fetch all data from open source and transform it into a usable hash.
Beer class - would receive a hash from Api class and create attributes.
Cli class - would communicate with the user by main #call method.
test.rb - the place where 3 classes would first see the "light of a day". The focus was on making it work without worrying about file communication.

Bundle install
$mkdir folder_name
=> create a new folder for your project
$cd folder_name
=> change the current working directory to folder build for your new project
$pwd
=> print Current Working Directory, just to check are you in the right one
$ bundle gem project_name
=> creates a whole structure with files and folders
=> naming your gem

bin folder - This would be the entering point of our program, this is where you will create your run file.
$touch beer_projet
=> this will create a new file in our bin folder
$ls -lah
=> list of all files (example: drwxr--r-- file_name), where we can see if it is executable or not
=>file that we made will not have "x" which means it doesn't have "executable permission".
$chmod +x beer_project
=> add "executable permission".
./bin/beer_project
line 1. #!/usr/bin/env ruby - this will tell our file in what environment he needs to run it (since there is no file extension this is needed).
line 5. the "run" file needs to "look" only at your environment file by "require_relative" it.

lib folder
Place of your environment.rb file (originally it was named beer_project.rb) and folder that will contain all our classes in separate files.

Api class
Is responsible to "fetch" data from provided url with help of httparty gem and convert it into a usable hash that will be forwarded to Beer class.

Beer class
Every time beer_hash is created in Api class it will instantiate Beer class to create a new instance with attributes provided by beer_hash.

Cli class
Creating a call method was something that gave me a lot of headaches. binding.pry was really helpful but in the end, I went back to Repl to build a skeleton for the main method. It was faster to test concepts and there was less distraction. Here I used and abused the idea of helper methods which gave me a better approach for debugging my call method.
Git
$git status => checking if we have a git already build if no then we can run:
$pwd => if we are in the right folder
$git init => create git
$git status => show us all altered files
$git add . => add all files to the staging area, where we can also go by folder name if we want to add only a specific file
$git commit -m "message" => commit files from staging area to our local git with a message of choice
Github
On my Github page, I create a new repository named "beer_project".
Back in terminal(all these commands will be offered on your Github):
$git remote and origin "github.com..."
$git branch -M main
$git push -u origin main

These were the main steps for my first CLI project after which fine-tuning came in place (resolving a few "bugs" along with typos which I am sure can be found here as well).
Anyway, for the very first time since starting the Flatiron software engineering course, I was in front of a whiteboard that needed to become a command-line interface application. It felt more than once overwhelming but going back to the lessons and videos provided by FI was big help. Our cohort leader and those open hours were great resources that helped me more than once to bring this phase and project to an end.

First-mile blog

Milan Zivkovic — Sun, 20 Dec 2020 21:26:08 +0000

Reminiscing
The only subject in high school that I didn’t have a problem with was Math. The reason for this was that it felt like training. Some light warming up, a bit of reading, one more set on ergometer, one more set in the gym, one more problem to solve…the more time you spend running, reading, rowing, studying, biking,... the better you will be, really keeps you on track.

Wrong track
A few years later it’s time to go to college. Not knowing what I wanted to do I ended up hopping on the wrong “train”. No matter how long you ride it, all the stations you pass along seem wrong. Biology, Ecology, Chemistry were nice but nothing that I would get hung upon. To be perfectly honest, I only stayed for scholarships and dorms, and those were not given easily. You had to keep your grades high since the evaluation was every year. It was my way to be independent in a “big” city. Looking back I wish I had exited the first station and hitchhiked back not caring what anybody would say. But that would mean to “get out of the box”.

Is it wrong if it feels right?
Fast forward a few years and I am M.S. in the Faculty of Science with no clue what to do next. When the position of teaching assistant at my university came as an option I grabbed it with both hands. This was a very productive time. People around me were very open and helpful. Working in a group, project deadline, and daily work in the lab with students was challenging as much as rewarding. After two years I felt it was the right time to try myself in a new field.

“The Real” world
Performance pressure was something that I encountered here for the first time since exams in College. This time it was about money! Weekly and monthly statistics about team performance, scoreboard, gross/net were new tests to pass and ace! It was definitely out of my comfort zone at the time. For over 7 years in logistics in almost all positions in the company (but CEO, :) ) I witnessed job shifting toward new technologies. As time went by people had to learn and adapt to new software and less manual work. More and more companies were looking for software engineers to solve problems they had or to upgrade their business.

Research
Learning how new software is working, getting faster at it was part of the job but how it’s built was picking my brain. FreeCodeCamp was the first place I stumbled upon, then came Udemy and a lot of tutorials on YT. It felt nice learning new things but the sound of a squeaky brain was so annoying. It took me a while before I learned enough JS syntax to solve my first coding challenge and even more to build my first web app. It was a simple calculator converting running pace to projected finish time on a race. Nothing much but it’s a handy tool that I am still using before or after every run. Knowing how much better you become by running with a group, how someone can give you a push or that you can pull someone if he is slipping brought me to Flatiron.

“The right train”
Now I am a Flatiron student on a software engineering course, learning about Ruby, discussing code with others, and feeling really good about this road we all started. The first station is just around the corner and this genuinely feels like the right train for me!