Restructure the content and use Hugo modules now
10
content/_index.adoc
Normal file
@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Homepage
|
||||
---
|
||||
|
||||
= Homepage
|
||||
|
||||
Hey there!
|
||||
Welcome to my small home on the deepest corners of the internet.
|
||||
Just a hobbyist programmer and a wannabe creative artisan productively wasting time on looking on other inspirations. :)
|
||||
|
@ -1,6 +1,5 @@
|
||||
---
|
||||
title: About
|
||||
date: 2019-08-15T11:25:01+08:00
|
||||
---
|
||||
|
||||
= About the author
|
||||
|
@ -1,6 +1,5 @@
|
||||
---
|
||||
title: "Archives"
|
||||
date: 2019-09-02T02:14:17+08:00
|
||||
type: "archive"
|
||||
---
|
||||
|
||||
|
@ -1,36 +0,0 @@
|
||||
---
|
||||
title: "Feeds"
|
||||
date: 2019-09-03T15:05:29+08:00
|
||||
type: "feed"
|
||||
---
|
||||
|
||||
= Feeds
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-09-03
|
||||
|
||||
Here's some of my feeds you can subscribe from:
|
||||
|
||||
* **RSS**: https://foo-dogsquared.github.io/blog/index.rss
|
||||
* **Atom**: https://foo-dogsquared.github.io/blog/index.atom
|
||||
* **JSON**: https://foo-dogsquared.github.io/blog/index.json
|
||||
|
||||
You can also be subscribed for specific sections with the
|
||||
following URL:
|
||||
|
||||
----
|
||||
https://foo-dogsquared.github.io/blog/$SECTION/index.$FEED
|
||||
----
|
||||
|
||||
For example, this is the feed URL for my posts (pretty much this
|
||||
is the only section available in my blog, for now):
|
||||
|
||||
* **RSS**: https://foo-dogsquared.github.io/blog/posts/index.rss
|
||||
* **Atom**: https://foo-dogsquared.github.io/blog/posts/index.atom
|
||||
* **JSON**: https://foo-dogsquared.github.io/blog/posts/index.json
|
||||
|
||||
// Or even in my projects, letting you know if there's any new
|
||||
// project detailing comes up.
|
||||
|
||||
// * **RSS**: https://foo-dogsquared.github.io/blog/projects/index.rss
|
||||
// * **Atom**: https://foo-dogsquared.github.io/blog/projects/index.atom
|
||||
// * **JSON**: https://foo-dogsquared.github.io/blog/projects/index.json
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 42 KiB |
Before Width: | Height: | Size: 47 KiB After Width: | Height: | Size: 47 KiB |
@ -1,15 +1,18 @@
|
||||
---
|
||||
title: "A 'ricing' starting checklist"
|
||||
date: 2019-08-25T18:03:43+08:00
|
||||
categories: ["linux"]
|
||||
tags: ["foss", "ricing", "linux"]
|
||||
categories:
|
||||
- How to Linux
|
||||
tags:
|
||||
- linux
|
||||
- desktop
|
||||
- ricing
|
||||
---
|
||||
|
||||
= A "ricing" starting checklist
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-08-19
|
||||
|
||||
:imagesdir: ../images/a-ricing-starting-checklist/
|
||||
|
||||
I just started ricing at the start of August 2019.
|
||||
So I made this list of things you might want to know when
|
||||
@ -183,7 +186,7 @@ For Arch Linux, it has Raleigh as the default GTK theme which looks
|
||||
very dated if you ask me.
|
||||
|
||||
.GTK Raleigh theme
|
||||
image::gtk-raleigh-theme-demo.webp[GTK Raleigh theme]
|
||||
image::images/gtk-raleigh-theme-demo.webp[GTK Raleigh theme]
|
||||
|
||||
For my custom configuration, I chose the https://github.com/NicoHood/arc-theme[Arc]
|
||||
theme along with its https://github.com/NicoHood/arc-icon-theme[icon set] simply
|
||||
@ -191,7 +194,7 @@ because they're the popular choice. I also think the darker scheme is pretty
|
||||
cool.
|
||||
|
||||
.GTK Arc Darker theme
|
||||
image::gtk-arc-darker-theme-demo.webp[GTK Arc Darker theme]
|
||||
image::images/gtk-arc-darker-theme-demo.webp[GTK Arc Darker theme]
|
||||
|
||||
You can look for more GTK themes at https://www.gnome-look.org/[GNOME Look].
|
||||
|
||||
@ -286,7 +289,7 @@ server. Simply sending a notification with `notify-send` while running Dunst in
|
||||
background can go a long way.
|
||||
|
||||
.Using dunst for screenshot notifications
|
||||
image::dunst-screenshot-demo.webp[Using dunst for screenshot notifications]
|
||||
image::images/dunst-screenshot-demo.webp[Using dunst for screenshot notifications]
|
||||
|
||||
I also made it to send notifications for delayed screenshots.
|
||||
|
||||
@ -302,7 +305,7 @@ different ways on where to store their configuration files.
|
||||
|
||||
NOTE: Dotfiles simply means your configurations of the installed
|
||||
programs. Its name also came from how Linux considers a file/folder
|
||||
with a period in front of the name to be hidden (i.e.: `.config`,
|
||||
with a period in front of the name to be hidden (i.e., `.config`,
|
||||
`.vimrc`, `.bashrc`).
|
||||
|
||||
If you would continue with no tool at all, you would most likely:
|
@ -1,8 +1,10 @@
|
||||
---
|
||||
title: A site overhaul has occurred
|
||||
date: 2019-08-15T18:10:07+08:00
|
||||
categories: ["meta"]
|
||||
tags: ["self", "meta"]
|
||||
|
||||
tags:
|
||||
- self
|
||||
- meta
|
||||
---
|
||||
|
||||
= A site overhaul has been occurred
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
@ -2,17 +2,17 @@
|
||||
title: "Blogging with Asciidoctor and Hugo"
|
||||
date: 2019-09-03T13:07:43+08:00
|
||||
categories:
|
||||
- guide
|
||||
- Hugo
|
||||
tags:
|
||||
- asciidoctor
|
||||
- blog
|
||||
- writing
|
||||
- ssg
|
||||
- hugo
|
||||
---
|
||||
|
||||
= Blogging with Asciidoctor and Hugo
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-08-27
|
||||
|
||||
:imagesdir: ../images/blogging-with-asciidoctor-and-hugo/
|
||||
:asciidoctor_site: https://asciidoctor.org/
|
||||
|
||||
Finally, I've found a great blogging workflow with Hugo and Asciidoctor.
|
||||
@ -264,7 +264,7 @@ The most obvious is the HTML output of Asciidoctor with the default
|
||||
backend is not great and leaves a lot of things to be desired.
|
||||
|
||||
.`<div>` then a `<p>` for a paragraph, really?
|
||||
image::asciidoctor-sample-html.webp[`<div>` then a `<p>` for a paragraph, really?]
|
||||
image::images/asciidoctor-sample-html.webp[`<div>` then a `<p>` for a paragraph, really?]
|
||||
|
||||
It's not semantic and it is unconventional.
|
||||
Not only that it's a pain to style it with CSS but also breaks a lot
|
@ -1,693 +0,0 @@
|
||||
---
|
||||
categories: ["self"]
|
||||
date: 2019-04-30 12:32:40 +0800
|
||||
tags: ["projects", "foss", "software-development"]
|
||||
title: Developing projects with free resources
|
||||
---
|
||||
|
||||
= Developing projects with free resources
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-04-30
|
||||
|
||||
In a world where technology has made it possible to inform and share
|
||||
experiences with other people through multiple devices, the technology
|
||||
sure came to advance at a point where the people themselves have the
|
||||
resources needed to establish and maintain businesses on their garage or
|
||||
bedroom.
|
||||
|
||||
The same can be said with creating projects. Being a student on a
|
||||
financial tightrope, it will be a fun and frustrating challenge to
|
||||
create projects with only free resources and services.
|
||||
|
||||
In this article, I'll share my experiences and tools I've used
|
||||
throughout my side-project and self-learning development journey while
|
||||
getting around paid services.
|
||||
|
||||
____
|
||||
BIG UPDATE: Added a section for publishing your projects. I simply
|
||||
forgot to add it which is why I felt it's complete by the time I
|
||||
published this post. Apologies about that. :facepalm:
|
||||
____
|
||||
|
||||
|
||||
== TL;DR version
|
||||
|
||||
Here are the tools I've used usually for planning and brainstorming
|
||||
software ideas:
|
||||
|
||||
* https://www.draw.io/[Draw.io]
|
||||
* https://www.figma.com/[Figma]
|
||||
* https://quire.io/[Quire]
|
||||
* just a plain pen & paper
|
||||
|
||||
When a plan is up, time to make it real. Here are the tools I'm using:
|
||||
|
||||
* https://git-scm.com/[Git]
|
||||
* https://www.jetbrains.com/[Jetbrains IDE]
|
||||
* https://code.visualstudio.com/[Visual Studio Code]
|
||||
* a lot more tools as you read on
|
||||
|
||||
When the project has been realized (if not dropped). These services and
|
||||
platforms let you share your project for free:
|
||||
|
||||
* https://github.com/[GitHub]
|
||||
* https://www.netlify.com/[Netlify]
|
||||
* http://heroku.com/[Heroku]
|
||||
|
||||
Of course, this list is not really complete. You can see more tools that
|
||||
deserve honorable mentions as you read on.
|
||||
|
||||
|
||||
== Planning my projects
|
||||
|
||||
Planning is a part of the process. It's an ever-important process that
|
||||
prevents your software project (or any project) to be an aftermath of a
|
||||
great natural disaster. It's not guaranteed for your project to go
|
||||
smooth accordingly but it's better to have a plan than going straight
|
||||
into the battlefield.
|
||||
|
||||
[quote, Captain Cold]
|
||||
There are only 4 rules you need to remember: make the plan, execute the
|
||||
plan, expect the plan to go off the rails, throw away the plan.
|
||||
|
||||
If the plan failed, just go through another planning phase. The action
|
||||
does not apply well into a production workflow with the chaotic and
|
||||
larger-scale management but it can be easily apply for personal
|
||||
projects.
|
||||
|
||||
Here are the tools I've used to practice my planning skills:
|
||||
|
||||
=== https://quire.io/[Quire]
|
||||
|
||||
Quire is an online tool for almost everything productivity-based. I mean
|
||||
they got https://quire.io/features[an exhaustive list of features] from
|
||||
kanban boards, simple task lists, integration to different services such
|
||||
as GitHub, Google Drive, and Slack, and much more!
|
||||
|
||||
The best part about all of this is that it looks minimalistic with all
|
||||
of its features. It goes out of your way with all of its features to use
|
||||
as you intended. You want to look at your task board for your project
|
||||
and the website only shows you that.
|
||||
|
||||
==== Alternatives
|
||||
If Quire is not your fancy, then may I introduce you to some of the
|
||||
alternatives?
|
||||
|
||||
* https://trello.com/[Trello] — It's a good boi but not enough features
|
||||
for me. It features a powerful board with powerful integrations but for
|
||||
the most part, it limits right there and there's not much of a
|
||||
difference with the core features you'll be using with Quire.
|
||||
* https://www.notion.so/[Notion] — Well, this one is a solid
|
||||
alternative. This is mainly a minimalistic online note-taking tool
|
||||
suitable for your notes, projects, and other shenanigans but it also
|
||||
features a lightweight task and issue board for your projects, a
|
||||
lightweight database, and a lightweight customer relation management
|
||||
(CRM) system. I mainly use this app for a quick note-taking while saving
|
||||
it online but it can also go head-to-head with Quire as a productivity
|
||||
tool with a different twist.
|
||||
|
||||
Now if you go with Notion, may I get you with a deal? You can click
|
||||
https://www.notion.so/?r=ed358a0e3f6d4e47a5db21a17beaa7dd[my referral
|
||||
link] and get $10 in credits while I get 5 USD in credits. It's a
|
||||
win-win situation and you'll be able to help me.
|
||||
|
||||
=== https://www.draw.io/[Draw.io]
|
||||
|
||||
This is my personal digital "drawing" tool (and also the tool I used to
|
||||
create visual aids for this blog). It's a web-based tool that allows you
|
||||
to create a wide range of visual design assets from flowcharts to not
|
||||
flowcharts. Speaking of web-based, you can also download
|
||||
https://about.draw.io/integrations/#integrations_offline[desktop
|
||||
versions] of it and use it offline though the site itself already
|
||||
features an offline web-based version of the tool.
|
||||
|
||||
One of the best features of this app is that *it's free and
|
||||
https://github.com/jgraph/drawio[open source]*. Being open source not
|
||||
only means you can see the naked source code used to build the app but
|
||||
also you can directly contribute to it.
|
||||
|
||||
Another one superb feature is that *no account registration is required
|
||||
to use this app*! When you open the website, you're already going
|
||||
straight into the business. No briefing, no meetup, no orientation.
|
||||
|
||||
From that point, you can create universally almost any diagrams from
|
||||
concept maps, simple flowchart,
|
||||
https://en.wikipedia.org/wiki/Unified_Modeling_Language[UML diagrams],
|
||||
https://www.visual-paradigm.com/guide/data-modeling/what-is-entity-relationship-diagram/[database
|
||||
relationship diagrams], mathematical expressions, or even an
|
||||
illustration. It features a solid UI and a collection of features that
|
||||
makes visual aids creation to be as much pleasing as possible.
|
||||
|
||||
==== Alternatives
|
||||
If you want to try out other similar tools for comparison, here are some
|
||||
alternatives I've gathered:
|
||||
|
||||
* https://www.libreoffice.org/discover/draw/[LibreOffice Draw] (or
|
||||
Microsoft Visio, if you're into Windows) — LibreOffice free and
|
||||
https://www.libreoffice.org/about-us/source-code/[open source] software
|
||||
suite for office work. It offers a program to write documents, create
|
||||
and edit spreadsheets, make presentations, manage databases, and draw
|
||||
diagrams. It's a solid alternative and it has some stronger points such
|
||||
as how pathfinding was handled (especially with the lines and arrows).
|
||||
However, Draw.io being a web-based tool and having a solid feature list
|
||||
in its arsenal is too hard to beat for me. In any case, I would still
|
||||
give this a shot.
|
||||
* https://inkscape.org/[Inkscape] — It's another free and open source
|
||||
vector editing application that run on major desktop platforms. Despite
|
||||
its stronger points on vector illustration, it still has solid support
|
||||
for creating diagrams. Like LibreOffice Draw, it has more solid handling
|
||||
on the pathfinding part of the shapes compared to Draw.io. However, in
|
||||
order to fully use its full diagramming potential, you may have to take
|
||||
more time to get used to it. I think the efforts will pay off once you
|
||||
done it and in fact, you may create more expressive and powerful
|
||||
diagrams with it. Take note that the program (at the time of this
|
||||
writing) is not yet at its 1.0 version yet which means it still has
|
||||
issues to clean out. Being a free and open source project, you can help
|
||||
with the development through issues, bug reports, doc improvement, and
|
||||
code contribution.
|
||||
|
||||
=== https://www.figma.com/[Figma]
|
||||
|
||||
If have a core feature for my planned side project, it's time to make
|
||||
the idea closer to reality by making a user interface for that idea.
|
||||
Here's where I brainstorm forms and layouts my idea can have as a
|
||||
tangible service and it's where Figma comes in.
|
||||
|
||||
Figma is another web-based program used to create GUI prototypes and
|
||||
designs. It can also serve as an alternative to Draw.io as a diagramming
|
||||
and illustration program but that's not the main point we will tackle.
|
||||
Also take note I have little experience with using this app so feel free
|
||||
to correct me on the stuff that I'll be saying here.
|
||||
|
||||
Since the initial writing for this app is too long (it's really that
|
||||
good), I'll be making a quick list of features and discuss them shortly
|
||||
instead:
|
||||
|
||||
* It is *free to use and web-based*. Though, it requires an account to
|
||||
use it, it's not much of an inconvenience once you get a hold of this
|
||||
app. Being a web-based tool, you can run this anywhere as long as the
|
||||
machine has WebGL and a compatible web browser.
|
||||
* It *features a strong user interface (UI) and user experience (UX)*.
|
||||
The UI is good that
|
||||
https://twitter.com/foo_dogsquared/status/1102486132648960000[I could
|
||||
create my first custom-made logo with it] despite being inexperienced
|
||||
with graphics design.
|
||||
* It *features a collaborative mode* similar to Google Docs. With the
|
||||
pain points of being in a collaborative environment, they also *feature
|
||||
a version control for the sketches*.
|
||||
* It *works offline* except for online functionalities such as saving
|
||||
your sketches on the cloud and collaboration mode.
|
||||
* Has *standard feature arsenal* such as shape tools, pen tool, gradient
|
||||
tool, importing images, and linking to individual pages. It does not
|
||||
stop there. They have *a
|
||||
https://www.youtube.com/watch?v=k74IrUNaJVk[component system] and a
|
||||
https://www.youtube.com/watch?v=b-xDRjf5B-8[powerful vector editing
|
||||
tool]* that'll expand your options of smoothly creating unique-looking
|
||||
assets.
|
||||
|
||||
If you'll try this one, you can sign up for an account,
|
||||
https://www.youtube.com/playlist?list=PLXDU_eVOJTx7QHLShNqIXL1Cgbxj7HlN4[watch
|
||||
their Getting Started playlist on YouTube], and experiment ahead.
|
||||
|
||||
==== Alternatives
|
||||
Is Figma too complex of a tool for your use case? Here are some
|
||||
alternatives you can search for:
|
||||
|
||||
* https://pencil.evolus.vn/[Pencil] — A free and open source GUI
|
||||
prototyping platform. Unfortunately, it's not maintained anymore and the
|
||||
most recent version is from 2017 but it still offer a solid and simpler
|
||||
GUI prototyping process for websites and desktop apps.
|
||||
* https://www.draw.io/[Draw.io] — I already discussed this tool so I
|
||||
won't give much details but you can also use this for simpler
|
||||
prototyping processes. It just depends on how you would use these tools.
|
||||
|
||||
=== Good ol' pen & paper
|
||||
|
||||
Well all I need is a way of planning for my project. What a better way
|
||||
of planning than a good ol' P&P. One of its most useful feature is that
|
||||
it's quick to load! No internet connection needed! It's a universal
|
||||
alternative to all the apps listed so far. The only situation you're not
|
||||
able to boot this up is if you don't have the materials yourself.
|
||||
|
||||
In all seriousness though, I think this is one of the most useful ones.
|
||||
Physically writing is actually more memorable (to me, at least) thus
|
||||
more things to remember. Besides, I don't want to stare at a digital
|
||||
screen all day.
|
||||
|
||||
Usually when I'm going to plan with this method, I follow through a
|
||||
system I created for myself. The system is nothing fancy. It's just a
|
||||
color-coded system with each colored paper shows the priority level for
|
||||
each task I will make.
|
||||
|
||||
If you want to try it for yourself, I'll give you my personal take on
|
||||
the system:
|
||||
|
||||
Now there are three types of tasks in this system: low, normal, and
|
||||
essential. They're basically another way of indicating priorities on
|
||||
your tasks. There's also another type of paper which is basically a
|
||||
reviewer of related concepts to be integrated with the project.
|
||||
|
||||
* *Green colored papers* _indicate low priority tasks_. This is usually
|
||||
the easy stuff and the low-hanging fruits of the project.
|
||||
* *Blue colored papers* _indicate normal priority tasks_. In the project
|
||||
development process, this is usually the things that is done after the
|
||||
core of the project has been completely (or mostly) developed.
|
||||
* *Yellow colored papers* _indicate essential tasks_. This is usually
|
||||
the core tasks and they're highly prioritized. I usually associate red
|
||||
with urgency but whatever fits your boat. I think yellow is a better
|
||||
choice since it stands out among the shades of blue and green.
|
||||
* *White colored papers* _indicate related concepts to the project_.
|
||||
This can be anything from a simple flashcard, an explainer, or a
|
||||
definition. Heck, you can put a thesis in there if you really want to.
|
||||
Speaking from personal experience, one of the role of this paper is to
|
||||
simply make you focus into the core concepts of your project so you
|
||||
couldn't easily sway and make a bunch of unrelated features and
|
||||
highlights in your project straight away. Also, it's just there to
|
||||
remind myself of the things I was supposed to learn.
|
||||
|
||||
Take note you don't have to buy colored papers for this one. One of the
|
||||
beauty of life is the freedom on how to do things and this is no
|
||||
exception. You could do say, just a simple format to express the core
|
||||
feature of this system which is _prioritization_. You can list out tasks
|
||||
and create symbols to express different levels of priority.
|
||||
|
||||
|
||||
== Creating my projects
|
||||
|
||||
When you have a plan in place, you can attack it in your own pace. This
|
||||
is the phase where you'll actually * get your envisioned project closer
|
||||
to reality*. Since we're in the context of software, I'll talking about
|
||||
the tools and experiences I was able to use and... experience.
|
||||
|
||||
If you want to know the tools outside of software for some unspecified
|
||||
reason, you can get a rough idea http://freebies-hunt.netlify.com/[in my
|
||||
relatively recent launched website, Freebies Hunt]. As specified in its
|
||||
name, all of the resources listed there are free (and some being open)
|
||||
so you'll be able to have a similar toolset as mine.
|
||||
|
||||
So what are the tools I used for this? Read on and find out.
|
||||
|
||||
=== https://code.visualstudio.com/[Visual Studio Code]
|
||||
|
||||
My go-to text editor and lightweight IDE. This tool is just phenomenal!
|
||||
It's free and https://github.com/Microsoft/vscode[open source],
|
||||
https://code.visualstudio.com/updates/[actively being developed], backed
|
||||
up by a huge community of developers, solid UI/UX for budding
|
||||
developers, https://code.visualstudio.com/docs[features an extensive
|
||||
documentation in using the app], and offers hackability that extends the
|
||||
app even further.
|
||||
|
||||
Of course, this tool still has its
|
||||
https://github.com/Microsoft/vscode/issues[issues] but with the active
|
||||
development from the core maintainers and other contributors, you know
|
||||
that it'll have a great future. With that said, this tool is not a
|
||||
panacea for our development tool problems. The core scope of this tool
|
||||
is limited outside of web development especially when compared to
|
||||
comprehensive IDEs such as https://visualstudio.com/[Visual Studio] and
|
||||
https://www.jetbrains.com/[Jetbrains IDE product line]. Even though it
|
||||
can be extended with the user-created plugins, when compared to
|
||||
first-party solutions, it's not usually enough (though there are
|
||||
exceptions).
|
||||
|
||||
==== Alternatives
|
||||
Want to try other text editors? Here's a list of it:
|
||||
|
||||
* https://atom.io/[Atom] — A free and open source text editor made by
|
||||
the team at https://github.com/[GitHub] and it can be considered as the
|
||||
most fitting rival with Visual Studio Code. They're both made with
|
||||
https://electronjs.org/[Electron]. Both offer similar set of features
|
||||
from hackability to the user interface. Atom, however, has a stronger
|
||||
focus on Git integration (specifically with GitHub). Basing from
|
||||
personal experience, you can already have the same level of focus on
|
||||
Visual Studio Code with the
|
||||
https://marketplace.visualstudio.com/search?term=git&target=VSCode&category=All%20categories&sortBy=Relevance[third-party
|
||||
plugins] and improving Git integration.
|
||||
* https://www.gnu.org/software/emacs/[GNU Emacs] — A family of text
|
||||
editor mostly known for its extensibility but specifically were looking
|
||||
at GNU Emacs which is the most popular member of the family. Compared to
|
||||
other text editors we've featured so far, this text editor has a steeper
|
||||
learning curve to master it especially when going from absolute zero. It
|
||||
also features integration with https://www.gnu.org/software/gdb/[GDB] (a
|
||||
debugger) making it into a lightweight IDE, has tons of keyboard
|
||||
shortcuts, features multiple modes, and best of all, you can play tetris
|
||||
with it (seriously). If you want to look further, you can take
|
||||
https://www.gnu.org/software/emacs/tour/index.html[a tour of Emacs from
|
||||
the GNU website] and see what more things Emacs can do.
|
||||
* https://www.vim.org/[Vim] — If you're hardcore, take a look into a
|
||||
text editor infamously known for its... difficulty. Anyway, I'm pretty
|
||||
sure you've heard of Vim by now after seeing it being memed to death.
|
||||
Vim is a text editor that utilizes the modal philosophy where it
|
||||
utilizes a different mode for editing files and inserting text. Like
|
||||
Emacs, it has a steep learning curve with its unconventional way of
|
||||
manipulating files. It's also programmable and contains a _lot_ of
|
||||
keyboard shortcuts and configuration options that you'll find
|
||||
https://github.com/search?q=vimrc[a community of developers sharing
|
||||
their Vim configuration files]. If you want a shallow dive into Vim, you
|
||||
can use this https://hacker-tools.github.io/editors/[course lecture]
|
||||
I've used.
|
||||
|
||||
=== https://www.jetbrains.com/[Jetbrains IDE]
|
||||
|
||||
If my project is in a larger scope or is in need for a more specialized
|
||||
tool, I might use an IDE. A personal example could be making a project
|
||||
with C++ and I need to learn more on using https://cmake.org/[CMake]. If
|
||||
you need to develop in https://golang.org/[Go],
|
||||
https://docs.microsoft.com/en-us/dotnet/csharp/[C#], or in
|
||||
https://www.arduino.cc/[Arduino], there are specialized tools that are
|
||||
built for that.
|
||||
|
||||
My IDEs of choice are from Jetbrains, a software development company
|
||||
whose product targets developers, where they offer a netful of IDEs for
|
||||
different programming languages and toolsets. Their IDEs have reached a
|
||||
wholesome reputation with plentiful of useful features and active
|
||||
development updates. Not to mention that they can run across all major
|
||||
platforms in Windows, Mac OS, and Linux which really sold me on this
|
||||
one. Though the only problem is that they're proprietary but they do
|
||||
offer free licenses on all of their tools
|
||||
https://www.jetbrains.com/student/[for students] (which I did) and
|
||||
https://www.jetbrains.com/opensource/[for developers of non-commercial
|
||||
open source projects].
|
||||
|
||||
==== Alternatives
|
||||
Fortunately, some of the IDEs have a free community version though it's
|
||||
usually inferior compared to the proprietary versions. Though, they're
|
||||
mostly enough especially in the beginning of the development. However,
|
||||
if you're looking for a free and more robust IDE, you could look into
|
||||
the following alternatives:
|
||||
|
||||
* https://visualstudio.com/[Visual Studio] — If you're using Windows or
|
||||
Mac OS, this could be a solid choice. Not only that it supports most of
|
||||
the popular programming languages and toolsets but it is also _free_.
|
||||
The Visual Studio installation process lets you customize your
|
||||
development environment according to your need whether you want to
|
||||
create cross-platform programs with C++ or want to get started on game
|
||||
development with Unity or even both, why not. There's plenty of choices
|
||||
you can make with this. The only gripe here is that it's not available
|
||||
in Linux/BSD systems. I use this in particular when developing in
|
||||
Windows since their free community edition is just too good to pass up.
|
||||
* https://www.eclipse.org/eclipseide/[Eclipse] — It's basically the
|
||||
cross-platform open source version of Jetbrains where their product line
|
||||
of IDEs offer support on most of programming languages such as C/C++,
|
||||
PHP, Java, Rust, and many others. I don't know how high of a candle they
|
||||
hold today but I found it to be useful enough to get started.
|
||||
|
||||
This is not an exhaustive list of IDEs for you to try (I mean three
|
||||
items, really?) but I recommend to try and search if it doesn't make you
|
||||
satisfied. Here, https://github.com/sindresorhus/awesome[I got you a
|
||||
place to get started on your search].
|
||||
|
||||
=== https://git-scm.com/[Git]
|
||||
|
||||
Well, we all have our ways in saving our stuff. One of the ways I did
|
||||
(way back when I have completely no idea in programming) would be simply
|
||||
saving the file and adding a `+v2+` at the end of its name.
|
||||
|
||||
image::https://imgs.xkcd.com/comics/documents.png[title="My archiving skills in high school",float="right",align="center"]
|
||||
|
||||
Other would use a software that can automatically create backups.
|
||||
Nowadays, popular softwares for writing most likely have an auto-save
|
||||
feature built into the system: https://docs.google.com/[Google Docs],
|
||||
https://evernote.com/[Evernote], https://notion.so/[Notion],
|
||||
https://visualstudio.com[Visual Studio],
|
||||
https://code.visualstudio.com[Visual Studio Code],
|
||||
https://www.jetbrains.com/[Jetbrains IDEs] – you name it, they most
|
||||
likely have it.
|
||||
|
||||
For solo projects, it is practical enough but if you
|
||||
want to amp your version controlling skill then you can use a full-on
|
||||
_version control system_ (shortened as _VCS_). I won't discuss what a
|
||||
VCS here but you can take a quick overview from one of the training
|
||||
videos from GitHub.
|
||||
|
||||
This is where Git
|
||||
(https://en.wikipedia.org/wiki/Comparison_of_version_control_software[and
|
||||
its other competitors]) comes in. You can refer to
|
||||
https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F[more
|
||||
well-written posts about it].
|
||||
|
||||
One objective of using a version control system like Git is not only
|
||||
acts as an epic save button but it also makes collaborative works to
|
||||
progress smoother. This is great in cases that your project needs help
|
||||
from other people aside from you. Since you're in the same page as your
|
||||
other collaborators, you can go through the same process of adding
|
||||
contributions to your project.
|
||||
|
||||
Git is my go-to version control software. It is nice to work with and it
|
||||
has ton of free services that are integrated with it. Despite it's
|
||||
mostly used for software projects, it can be useful for non-software
|
||||
stuff though better and more specialized solutions may exist.
|
||||
|
||||
=== Other tools
|
||||
|
||||
Well, here's a list of tools that deserves an honorable mention:
|
||||
|
||||
* https://asciidoctor.org/[Asciidoctor] — A free and open source text
|
||||
processor for https://asciidoctor.org/docs/what-is-asciidoc/[Asciidoc],
|
||||
a lightweight text formatting language similar to
|
||||
https://daringfireball.net/projects/markdown[Markdown]. Unlike Markdown,
|
||||
the scope of Asciidoc is much higher that it enables you to create an
|
||||
entire book with complete features using only the vanilla syntax of
|
||||
Asciidoc. I think this is a solid alternative to Markdown with more
|
||||
out-of-the-box features and it is standardized so we won't have to worry
|
||||
more on using a particular Markdown flavor. I recommend to get started
|
||||
with https://asciidoctor.org/docs/[the docs], there's seriously a ton of
|
||||
stuff to be explored here.
|
||||
* https://kile.sourceforge.io/[Kile] — My most recent tool in my belt.
|
||||
It's an IDE (or rather integrated writing environment? IWE?) for writing
|
||||
https://www.latex-project.org/[LaTeX] documents. I've recently made my
|
||||
technical notes into LaTeX documents and it is amazing so far. I haven't
|
||||
tried all of the features yet but I can see continuing to write notes
|
||||
with it and find a way on how to publish them on the web painlessly.
|
||||
* https://www.gnu.org/software/make/manual/make.html[Make] — A
|
||||
cross-platform free and open source automation tool usually used for
|
||||
software projects. If you're not familiar with it and want to try and
|
||||
experiment with it, you can
|
||||
https://opensource.com/article/18/8/what-how-makefile[refer to this
|
||||
article] to get started.
|
||||
* https://pandoc.org/[Pandoc] — A cross-platform free and open source
|
||||
universal document converter for various file formats and even your own
|
||||
formats. It supports major writing file formats like LaTeX, HTML,
|
||||
Asciidoc, Markdown (along with other flavors), and Textile. From there,
|
||||
you can convert one file from another with PDF, EPUB, and other file
|
||||
formats.
|
||||
* https://www.gnu.org/software/octave/[Octave] — A free and open source
|
||||
computational environment made by https://www.gnu.org/[GNU Software] so
|
||||
you know it's good stuff. It mostly serve as an alternative to
|
||||
https://www.mathworks.com/products/matlab.html[MATLAB] for me. Speaking
|
||||
of MATLAB, it's also mostly (READ: mostly) compatible with MATLAB syntax
|
||||
so you don't have to do a full-on porting of the computations (if
|
||||
there's any). I mostly use this just for the more complex mathematical
|
||||
graphics though I may use LaTeX or maybe
|
||||
http://asymptote.sourceforge.net/[Asymptote] for the later notes.
|
||||
* https://tiddlywiki.com/[TiddlyWiki] — A single-file personal wiki made
|
||||
in JavaScript with the one file being an HTML file. This is absolutely
|
||||
one of the most fascinating projects I've ever seen out there. Not only
|
||||
that it's quite cool on the programming aspect but also on the
|
||||
note-taking aspect. It features a wiki that is both portable and
|
||||
distributable for you and your readers. You can also customize your
|
||||
TiddlyWiki at your own whim to its appearances and its function by
|
||||
creating plugins. With all of those features, I think this is a perfect
|
||||
platform to share my notes without much hassle.
|
||||
|
||||
|
||||
== Publishing my project
|
||||
|
||||
If you want your project to be available for the whole world to see, you
|
||||
have available free options that lets you do that. Starting with...
|
||||
|
||||
=== https://github.com/[GitHub]
|
||||
|
||||
When you want to share your project with the world for everyone to see,
|
||||
you need a server to do that. Fortunately, there are free services that
|
||||
does exactly that. Enter GitHub.
|
||||
|
||||
Majority of you readers might have heard of this before. After all, it
|
||||
is _one of the largest and most popular development platform_ out there
|
||||
for the software industry. It's also _the_ leading development platform
|
||||
for open source software. It is where the big kids of the tech industry
|
||||
hang out: Microsoft, Google, Linux Foundation, you name it.
|
||||
|
||||
Couple of that with the number of developers signed up, being the
|
||||
de-facto platform for the open source community, and the nature of open
|
||||
source, the network value is just too good to not ignore it especially
|
||||
if you're looking for a first step through the door of the industry.
|
||||
|
||||
GitHub offer practically free unlimited public and private repo (with
|
||||
limited collaborators) for your projects. Whether you want to show off
|
||||
your projects or to keep your projects safe in the cloud, GitHub has you
|
||||
covered. Being a software development platform, it has a variety of
|
||||
features to aid software development:
|
||||
|
||||
* Issue tracking that is open for other people with GitHub accounts.
|
||||
* An easy-to-use interface for forking, code review, and merge conflicts
|
||||
management.
|
||||
* Organizations can be created and invite other people to join and grant
|
||||
them level of access for your projects. Whether you want non-members to
|
||||
have a read-only access or can contribute alongside is a decision you
|
||||
can make.
|
||||
* GitHub also has a https://github.com/marketplace[marketplace of
|
||||
different services] making a part of your development process to go much
|
||||
smoother.
|
||||
* Offers a social place for code snippets called
|
||||
https://gist.github.com[GitHub Gists].
|
||||
* Built-in tools for reporting and monitoring your projects.
|
||||
* https://education.github.com/pack/[Grants aid for students to get
|
||||
started on their software development journey] which further makes
|
||||
GitHub more of a de-facto platform not only for seasoned developers but
|
||||
also for newcomers.
|
||||
|
||||
Anyways, if you're looking for an alternative to GitHub, here's some
|
||||
other Git-based web hosting sites:
|
||||
|
||||
* https://gitlab.com/[GitLab] is probably the closest competitor to
|
||||
GitHub. It offers pretty much everything GitHub has (except for the
|
||||
student pack) but it has some other tricks GitHub doesn't have:
|
||||
** Offers true unlimited public and private repos with unlimited
|
||||
collaborators so you can make your projects truly private here.
|
||||
** Has built-in CI/CD tools making GitLab an out-of-the-box suitable
|
||||
platform for DevOps development.
|
||||
** Can be self-hosted (meaning you can run GitLab locally in your own
|
||||
machine).
|
||||
* https://bitbucket.org/[Bitbucket] is another competitor to GitHub. Its
|
||||
core feature set is quite similar to GitLab: having built-in CI/CD
|
||||
tools, can be self-hosted, and has a ton of built-in integration with
|
||||
other services such as Trello and Slack.
|
||||
|
||||
=== http://heroku.com/[Heroku]
|
||||
|
||||
If you're looking to deploy your dynamic web app, look no further to
|
||||
Heroku. Heroku offers an infrastructure as a service that is made sure
|
||||
to be as easy as possible and it is sure easy in my experience so far.
|
||||
|
||||
Heroku just needs a Git repo from GitHub, GitLab, Bitbucket, and other
|
||||
platforms and you're mostly done. Just tweak the app further, store your
|
||||
secret credentials, enable related services for your app, and your app
|
||||
will set ablaze live on the web.
|
||||
|
||||
Alternatives:
|
||||
|
||||
* https://glitch.com/[Glitch] — One of the coolest alternative to
|
||||
Heroku. It's another app deployment platform but with the sense of
|
||||
community mixed in. It lets you remix other people's app as well as you
|
||||
let them remix your app (if you choose). This is a nice platform for
|
||||
your hobby projects though it https://glitch.com/help/languages/[only
|
||||
supports Node.js for now (as of this writing)].
|
||||
* https://zeit.co/now[Now] An app deployment service from Zeit. It
|
||||
offers a platform to deploy your web apps though you have to integrate
|
||||
it with your app instead of just placing your app and letting it run.
|
||||
Like Heroku, it also offers a generous free tier that is mostly enough
|
||||
for managing multiple hobby projects.
|
||||
* http://firebase.google.com/[Firebase] — An infrastructure-as-a-service
|
||||
(IaaS) later acquired by Google. It offers a generous free tier services
|
||||
if you're starting out but later it gets expensive as your project made
|
||||
through the limit. The only downside when using this is you have to
|
||||
integrate your app and may use some proprietary solutions along with it.
|
||||
* https://repl.it/[Repl.it] — Possibly one of the best alternatives to
|
||||
Heroku. Similar to Glitch, it's an online IDE that
|
||||
https://repl.it/site/languages[supports a lot of languages] and it got
|
||||
https://repl.it/discord[a community of hackers behind it]. It's a pretty
|
||||
cool tool especially for hobby projects and such. It is also open for
|
||||
other users in the Repl.it community, being able to fork your projects.
|
||||
|
||||
=== https://www.netlify.com/[Netlify]
|
||||
|
||||
If you want to publish your static website, no need to deploy it with
|
||||
Heroku since it'll just add to your monthly quota.
|
||||
https://www.netlify.com/[Netlify] is one of the perfect platforms for
|
||||
that.
|
||||
|
||||
Like Heroku, Netlify is a platform that aims to make web app deployment
|
||||
as easy as possible. Just create an account, login to Netlify, integrate
|
||||
your Git repo, and give configurations for deployment then celebrate!
|
||||
|
||||
It offers out-of-the-box integration with common web workflow like task
|
||||
runners and Git repos and
|
||||
https://www.netlify.com/products/build/[automates them through a work
|
||||
pipeline], doing all the dev-ops work for you. It's pretty fantastic
|
||||
especially if you're working solo.
|
||||
|
||||
Of course, https://www.netlify.com/pricing/[Netlify offers a generous
|
||||
free tier] limiting your account up to 100GB bandwidth for your list of
|
||||
deployed projects. For me, that is more than enough.
|
||||
|
||||
Of course, tons of alternatives are available but here's the following
|
||||
that topped the list for me:
|
||||
|
||||
* https://surge.sh/[Surge] — One of the more popular static site
|
||||
deployment tool. It's simply a deployment tool available in the command
|
||||
line. Also provides out-of-the-box integration with common workflows.
|
||||
* https://pages.github.com/[GitHub Pages] — If you're mainly a
|
||||
https://gitlab.com[GitLab] user,
|
||||
https://docs.gitlab.com/ee/user/project/pages/[GitLab also offers a
|
||||
similar service]. It's the free static web hosting service offered in
|
||||
GitHub. You can set some configurations for your static website such as
|
||||
the branch specified to hold your site's files. You could also create a
|
||||
quick landing page for your repo with it.
|
||||
* https://zeit.co/now[Now] — One of the more advanced alternative. It's
|
||||
a platform for static and dynamic sites. Available as a command line
|
||||
tool, the platform also offers a https://zeit.co/pricing[generous free
|
||||
tier].
|
||||
|
||||
With all of those above, you're practically set for life in your web
|
||||
development learning journey. It's pretty amazing that we get these
|
||||
stuff for FREE, mind you. Now go ahead and ship some apps.
|
||||
|
||||
=== Other tools
|
||||
|
||||
Well, here's some honorable mentions:
|
||||
|
||||
* https://travis-ci.org/[Travis CI] — A continuous
|
||||
integration/continuous deployment (CI/CD) service that integrates very
|
||||
well with GitHub which is the reason why I list it here. If you're not
|
||||
familiar with CI/CD systems yet, you can view
|
||||
https://www.youtube.com/watch?v=ymPOI4gWQFY&list=PL0zVEGEvSaeFFy32i5A4041qSTbYqtKqv[this
|
||||
video series by @mpjme from FunFunFunction] to get you started. The
|
||||
video series assumes that you're familiar with programming workflows (in
|
||||
which you're most likely to be since you're reading my posts right now).
|
||||
* Your own automation script. — In some cases or reason, you'll have to
|
||||
craft the deployment script yourself. You might write one of these since
|
||||
you don't want to rely on a CI/CD service or just want to deploy it
|
||||
yourself.
|
||||
* Your own backend, maybe? — If it's powerful enough, I guess you could
|
||||
but I recommend more to pass that responsibility to the companies that
|
||||
offer dedicated servers. Unless your project _revolves around deploying
|
||||
your own backend_, I don't see much reason to deploy it with your own.
|
||||
|
||||
|
||||
== Conclusion
|
||||
|
||||
There's my general workflow in its glory using only with (mostly) free
|
||||
and open source technologies. There's a lot more things to keep an eye
|
||||
on especially if you're looking for a specific set of technologies or
|
||||
needs. If you're looking for more open content, I can point you to the
|
||||
following:
|
||||
|
||||
* https://github.com/sindresorhus/awesome[`+awesome+`] — A list of
|
||||
resource list of various technologies and topics from software
|
||||
development, music, research, to game development. You should be able to
|
||||
get a start of your search of open content from there.
|
||||
* https://freebies-hunt.netlify.com/[Freebies Hunt] — I've created this
|
||||
website as a way of introducing you to free and open content, in
|
||||
general. It contains free resources for programming, music, design, and
|
||||
other interests I have. Quite similar to `+awesome+` but it stripped
|
||||
down to my preferred resources. Of course, for the spirit of open
|
||||
content (and software), everything on this website is open source from
|
||||
the https://github.com/foo-dogsquared/freebies-hunt[website] and the
|
||||
https://github.com/foo-dogsquared/freebies-hunt-api/[API] I've built.
|
||||
|
||||
One of the most beneficial things on free and open content today is that
|
||||
they're easily accessible as they're easily created. Not only that it
|
||||
does help on making the technology to easily create interest on the
|
||||
public but also to create progress by everyone.
|
||||
|
||||
Though with the said nature of open content, there are problems that are
|
||||
bound to be manifested such as the large amount of open content that can
|
||||
be completely overwhelming to newcomers up to the quality of the open
|
||||
content seeing as it can be made by everyone.
|
||||
|
||||
Overall, I don't think it can be a problem as long as there are leading
|
||||
bodies that govern and direct the advancement of the technology or the
|
||||
domain it operates with. (Of course there are problems bound with it as
|
||||
well but that's how life works, solving problem inherently creates
|
||||
another problem.)
|
||||
|
225
content/posts/developing-projects-with-free-resources/index.adoc
Normal file
@ -0,0 +1,225 @@
|
||||
---
|
||||
date: 2019-04-30 12:32:40 +0800
|
||||
title: Developing projects with free resources
|
||||
|
||||
categories:
|
||||
- How not to procastinate
|
||||
tags:
|
||||
- projects
|
||||
- development
|
||||
---
|
||||
|
||||
= Developing projects with free resources
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-04-30
|
||||
|
||||
:toc:
|
||||
|
||||
|
||||
In a world where technology has made it possible to inform and share experiences with other people through multiple devices, the technology sure came to advance at a point where the people themselves have the resources needed to establish and maintain businesses on their garage or bedroom.
|
||||
|
||||
The same can be said with creating projects.
|
||||
Being a student on a financial tightrope, it will be a fun and frustrating challenge to create projects with only free resources and services.
|
||||
|
||||
In this article, I'll share my experiences and tools I've used throughout my side-project and self-learning development journey while getting around paid services.
|
||||
|
||||
|
||||
|
||||
|
||||
== Planning my projects
|
||||
|
||||
Planning is a part of the process.
|
||||
It's an ever-important process that prevents your software project (or any project) to be an aftermath of a great natural disaster.
|
||||
It's not guaranteed for your project to go smooth accordingly but it's better to have a plan than going straight into the battlefield.
|
||||
|
||||
[quote, Captain Cold]
|
||||
There are only 4 rules you need to remember: make the plan, execute the
|
||||
plan, expect the plan to go off the rails, throw away the plan.
|
||||
|
||||
If the plan failed, just go through another planning phase.
|
||||
The action does not apply well into a production workflow with the chaotic and larger-scale management but it can be easily apply for personal projects.
|
||||
|
||||
Here are the tools I've used to practice my planning skills:
|
||||
|
||||
|
||||
=== https://quire.io/[Quire]
|
||||
|
||||
Quire is an online tool for almost everything productivity-based. I mean
|
||||
they got https://quire.io/features[an exhaustive list of features] from
|
||||
kanban boards, simple task lists, integration to different services such
|
||||
as GitHub, Google Drive, and Slack, and much more!
|
||||
|
||||
The best part about all of this is that it looks minimalistic with all
|
||||
of its features. It goes out of your way with all of its features to use
|
||||
as you intended. You want to look at your task board for your project
|
||||
and the website only shows you that.
|
||||
|
||||
|
||||
=== https://inkscape.org/[Inkscape]
|
||||
|
||||
Inkscape is a vector graphics tool and a free and open source software (FOSS) in similar veins of https://www.adobe.com/products/illustrator.html[Adobe Illustrator].
|
||||
It's a neat tool suited for a variety of basic tasks related for vector graphics: icon art, visual aids, and even https://wiki.inkscape.org/wiki/index.php/LaTeX[mathematical equations].
|
||||
I find Inkscape more approachable than Illustrator, further enhanced by its welcoming community.
|
||||
|
||||
It also offers extensiblity through plugins and gathered a community of designers and developers that extend Inkscape for their own needs (and maybe yours).
|
||||
I've mainly used Inkscape for creating diagrams and visual aids (and a little bit of vector art for practice).
|
||||
Though, using Inkscape for diagramming can be tricky and unintuitive so I recommend https://app.diagrams.net/[diagrams.net] (formerly known as draw.io).
|
||||
|
||||
|
||||
|
||||
|
||||
=== Good ol' pen & paper
|
||||
|
||||
Well, all I need is a way of planning for my project.
|
||||
Cite a better way of planning than a good ol' P&P.
|
||||
One of its most useful feature is that it's quick to load!
|
||||
No internet connection needed!
|
||||
It's a universal alternative to all the apps listed so far.
|
||||
The only situation you're not able to boot this up is if you don't have the materials yourself.
|
||||
|
||||
In all seriousness though, I think this is one of the most useful ones.
|
||||
Physically writing is actually more memorable (to me, at least) thus more things to remember.
|
||||
Besides, I don't want to stare at a digital screen all day.
|
||||
|
||||
Usually when I'm going to plan with this method, I follow through a system I created for myself.
|
||||
The system is nothing fancy, it's a simple priority task queue where I categorized whether the task is a low-hanging fruit, an afterthought, or a requirement.
|
||||
You could represent this with symbols, colored papers, or birds.
|
||||
|
||||
|
||||
|
||||
|
||||
== Creating my projects
|
||||
|
||||
When you have a plan in place, you can attack it in your own pace.
|
||||
|
||||
The following list is only for software projects but I recently launched https://freebies-hunt.netlify.app/[a website that lists all of the free resources and tools] I've used for a variety of tasks.
|
||||
|
||||
|
||||
=== https://code.visualstudio.com/[Visual Studio Code]
|
||||
|
||||
My go-to text editor and lightweight IDE.
|
||||
This tool is just phenomenal!
|
||||
It's free and https://github.com/Microsoft/vscode[open source], https://code.visualstudio.com/updates/[actively being developed], backed up by a huge community of developers, solid UI/UX for budding developers, https://code.visualstudio.com/docs[features an extensive documentation], and offers hackability that extends the app even further.
|
||||
|
||||
With that said, this tool is not a panacea for our development tool problems.
|
||||
The core scope is on web development when you look at the feature set: JavaScript and TypeScript support, built-in https://www.emmet.io/[Emmet] plugin, and built-in HTML and CSS support.
|
||||
Thankfully, Visual Studio Code has accumulated an ecosystem of quality plugins over the past years so things like adding support for a certain language like Rust, C++, or Java can be acquired.
|
||||
Along with some helpful utilities like https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop[LaTeX workflow], https://marketplace.visualstudio.com/items?itemName=vscodevim.vim[Vim emulation], and https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig[EditorConfig].
|
||||
|
||||
|
||||
=== https://git-scm.com/[Git]
|
||||
|
||||
Well, we all have our ways in saving our stuff.
|
||||
A certain XKCD comic said it best how I used to do it.
|
||||
|
||||
image::https://imgs.xkcd.com/comics/documents.png[title="My archiving skills in high school"]
|
||||
|
||||
Other would use a software that can automatically create backups.
|
||||
For solo projects, it is practical enough but if you want to amp your version controlling skill then you can use a full-on **version control system** (VCS).
|
||||
One objective of using a version control system like Git is not only acts as an epic save button but it also makes collaborative works to progress smoother.
|
||||
|
||||
Git is my go-to version control software.
|
||||
It is nice to work with and it has ton of free services that are integrated with it.
|
||||
Despite it's mostly used for software projects, it can be useful for non-software stuff though better and more specialized solutions may exist.
|
||||
|
||||
|
||||
|
||||
|
||||
== Publishing my project
|
||||
|
||||
If you want your project to be available for the whole world to see, you have available free options that lets you do that.
|
||||
|
||||
|
||||
=== https://github.com/[GitHub]
|
||||
|
||||
When you want to share your project with the world for everyone to see, you need a platform to do that.
|
||||
One of the popular options for that is GitHub (which requires using Git but it's ubitiquous nowadays).
|
||||
|
||||
GitHub offer practically free unlimited public and private repo (with limited collaborators) for your projects.
|
||||
Whether you want to show off your projects or to keep your projects safe in the cloud, GitHub has you covered.
|
||||
|
||||
Being a software development platform, it has a variety of features to aid software development such as issue tracking, code reviews, automation with https://github.com/features/actions[GitHub Actions], and built-in project management tools.
|
||||
|
||||
If you're looking for an alternative to GitHub, here's some other Git-based web hosting sites:
|
||||
|
||||
* https://gitlab.com/[GitLab] is probably the closest competitor to GitHub sporting a similar set of features.
|
||||
What's more, you can spin your own GitLab instance in case you want your own Git platform.
|
||||
|
||||
* https://bitbucket.org/[Bitbucket] is another competitor to GitHub.
|
||||
Its core feature set is quite similar to GitLab: having built-in CI/CD tools, can be self-hosted, and has a ton of built-in integration with other services such as Trello and Slack.
|
||||
|
||||
|
||||
=== http://heroku.com/[Heroku]
|
||||
|
||||
If you're looking to deploy your dynamic web app, look no further to Heroku.
|
||||
Heroku offers an infrastructure as a service that is made sure to be as easy as possible and it is sure easy in my experience so far.
|
||||
|
||||
Heroku just needs a Git repo and you're mostly done.
|
||||
Just tweak the app further, store your secret credentials, enable related services for your app, and your app will set ablaze live (or crash) on the web.
|
||||
|
||||
If you're looking for other hosts that support multiple languages and setup, have a look at the following list.
|
||||
|
||||
* https://glitch.com/[Glitch] — One of the coolest alternative to Heroku.
|
||||
It's another app deployment platform but with the sense of community mixed in.
|
||||
However, it's not suitable for production deployment.
|
||||
|
||||
* https://zeit.co/now[Now] is an app deployment service from Zeit.
|
||||
It offers a platform to deploy your web apps though you have to integrate it with your app instead of just placing your app and letting it run.
|
||||
Like Heroku, it also offers a generous free tier that is mostly enough for managing multiple hobby projects.
|
||||
|
||||
* http://firebase.google.com/[Firebase] offers a generous free tier which can take a while before reaching the limit if you're deploying a few personal dev projects.
|
||||
|
||||
* https://repl.it/[Repl.it] — Possibly one of the best alternatives to Heroku.
|
||||
Similar to Glitch, it's an online IDE that https://repl.it/site/languages[supports a lot of languages] and it got
|
||||
https://repl.it/discord[a community of hackers behind it].
|
||||
It's a pretty cool tool especially for hobby projects, personal demos, and such.
|
||||
|
||||
|
||||
=== https://www.netlify.com/[Netlify]
|
||||
|
||||
If you want to publish your static website, no need to deploy it with Heroku since it'll just add to your monthly quota.
|
||||
https://www.netlify.com/[Netlify] is one of the perfect platforms for that.
|
||||
|
||||
Like Heroku, Netlify is a platform that aims to make web app deployment as easy as possible.
|
||||
Just create an account, login to Netlify, integrate your Git repo, and give configurations for deployment then celebrate!
|
||||
|
||||
It offers out-of-the-box integration with common web workflow like task runners and Git repos and https://www.netlify.com/products/build/[automates them through a work pipeline], doing all the work for you.
|
||||
It's pretty fantastic especially if you're working solo.
|
||||
|
||||
Of course, https://www.netlify.com/pricing/[Netlify offers a generous free tier] limiting your account up to 100GB bandwidth for your list of
|
||||
deployed projects.
|
||||
For me, that is more than enough.
|
||||
|
||||
Of course, tons of alternatives are available but here's the following that topped the list for me:
|
||||
|
||||
* https://surge.sh/[Surge] — One of the more popular static site
|
||||
deployment tool. It's simply a deployment tool available in the command
|
||||
line. Also provides out-of-the-box integration with common workflows.
|
||||
|
||||
* https://pages.github.com/[GitHub Pages] offers similarly generous resources for your static apps.
|
||||
If you're mainly a https://gitlab.com[GitLab] user, https://docs.gitlab.com/ee/user/project/pages/[GitLab also offers a similar service].
|
||||
|
||||
* https://zeit.co/now[Now] is still one of them.
|
||||
|
||||
With all of those above, you're practically set for life in your webdevelopment learning journey.
|
||||
It's pretty amazing that we get these stuff for FREE, mind you.
|
||||
|
||||
|
||||
|
||||
|
||||
== Conclusion
|
||||
|
||||
There's my general workflow in its glory using only with (mostly) free and open source technologies.
|
||||
There's a lot more things to keep an eye on especially if you're looking for a specific set of technologies or needs.
|
||||
If you're looking for more open content, I can point you to the following:
|
||||
|
||||
* https://github.com/sindresorhus/awesome[`awesome`] — A list of
|
||||
resource list of various technologies and topics from software
|
||||
development, music, research, to game development. You should be able to
|
||||
get a start of your search of open content from there.
|
||||
|
||||
* It's a shameless plug but https://freebies-hunt.netlify.com/[Freebies Hunt] is a personally curated list of free resources that I've used for a variety of tasks including music production, 3D modelling, and art.
|
||||
|
||||
One of the most beneficial things on free and open content today is that they're easily accessible as they're easily created.
|
||||
Not only that it does help on making the technology to easily create interest on the public but also to create progress by everyone.
|
||||
|
@ -1,8 +1,12 @@
|
||||
---
|
||||
title: A freebie's resource list (mostly related to programming)
|
||||
date: 2018-05-01 09:25:57 +0800
|
||||
categories: [foss]
|
||||
tags: [foss, freebies]
|
||||
|
||||
categories:
|
||||
- Freebies
|
||||
tags:
|
||||
- bookmarks
|
||||
- freebies
|
||||
---
|
||||
|
||||
= A freebie's resource list (mostly related to programming)
|
||||
@ -80,7 +84,7 @@ project-based curriculum for web development
|
||||
* https://www.ixl.com/[IXL] — an educational resource and learning site
|
||||
on K-12 curriculum
|
||||
* https://khanacademy.org[Khan Academy] — *(recommended)*; there are
|
||||
also other topics outside of programming (i.e. mathematics, physics)
|
||||
also other topics outside of programming (i.e., mathematics, physics)
|
||||
* https://learnxinyminutes.com[Learn X in Y Minutes] — a
|
||||
community-created repository of summaries for you to learn the X
|
||||
programming languages
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 80 KiB |
Before Width: | Height: | Size: 4.8 KiB After Width: | Height: | Size: 4.8 KiB |
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 43 KiB |
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 54 KiB |
@ -1,15 +1,18 @@
|
||||
---
|
||||
title: "The complete Linux turnabout"
|
||||
date: 2019-08-20T20:50:18+08:00
|
||||
categories: ["linux"]
|
||||
tags: ["linux", "foss"]
|
||||
categories:
|
||||
- How to Linux
|
||||
tags:
|
||||
- linux
|
||||
- desktop
|
||||
- ricing
|
||||
---
|
||||
|
||||
= The complete Linux turnabout
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-08-20
|
||||
|
||||
:imagesdir: ../images/the-complete-linux-turnabout/
|
||||
|
||||
Ever since I found some good stuff at Linux, I wiped out my
|
||||
hard drive completely, exclusively install a Linux-based
|
||||
@ -67,7 +70,7 @@ It was easy to adapt to it since I'm completely used to using programs
|
||||
that live in a command line interface like https://www.vim.org/[Vim].
|
||||
|
||||
.My i3 setup
|
||||
image::i3-setup.webp[My i3 setup]
|
||||
image::images/i3-setup.webp[My i3 setup]
|
||||
|
||||
i3 also offers a level of https://i3wm.org/docs/userguide.html[configuration]
|
||||
that could make you a bit more efficient.
|
||||
@ -112,7 +115,7 @@ It's quite usable with rofi's sidebar mode where you can find windows, desktop e
|
||||
binaries, and even SSH configs.
|
||||
|
||||
.Customized rofi menu
|
||||
image::rofi-setup.webp[Customized rofi menu]
|
||||
image::images/rofi-setup.webp[Customized rofi menu]
|
||||
|
||||
You can find
|
||||
https://github.com/foo-dogsquared/dotfiles/tree/master/rofi[my rofi config on my GitHub repo].
|
||||
@ -199,7 +202,7 @@ file browser.
|
||||
status bar. It's pretty cool looking.
|
||||
|
||||
.Fullscreen Vim setup
|
||||
image::vim-setup.webp[Fullscreen Vim setup]
|
||||
image::images/vim-setup.webp[Fullscreen Vim setup]
|
||||
|
||||
If you want to take a deeper look or just want to see the full config,
|
||||
https://github.com/foo-dogsquared/dotfiles/tree/master/vim[you can see it in my dotfiles repo].
|
||||
@ -269,7 +272,7 @@ screenshot tool, keybinding tool, and a replacement for my status bar
|
||||
(which I didn't by the end of the day).
|
||||
|
||||
That's when I discovered https://www.reddit.com/r/unixporn/[`/r/unixporn`],
|
||||
a subreddit for showing off your *Nix (i.e.: Linux, MacOS) configurations and setup.
|
||||
a subreddit for showing off your *Nix (i.e., Linux, MacOS) configurations and setup.
|
||||
It's also a community for "ricing", an act of adding the visual spices to your setup.
|
||||
I recommend to check it out if you're looking for a starting point.
|
||||
They're pretty friendly for first timers, too.
|
Before Width: | Height: | Size: 112 KiB After Width: | Height: | Size: 112 KiB |
Before Width: | Height: | Size: 36 KiB After Width: | Height: | Size: 36 KiB |
After Width: | Height: | Size: 104 KiB |
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
@ -4,265 +4,264 @@ date: 2019-09-28T20:29:58+08:00
|
||||
cover: posts/images/the-importance-of-technical-writing-and-typography-in-a-software-project/cover.webp
|
||||
|
||||
categories:
|
||||
- software
|
||||
- Documentation
|
||||
tags:
|
||||
- writing
|
||||
- documentation
|
||||
- documentation
|
||||
---
|
||||
|
||||
= What is effective documentation
|
||||
= What is effective documentation
|
||||
Gabriel Arazas <foo.dogsquared@gmail.com>
|
||||
2019-09-19
|
||||
|
||||
:imagesdir: ../images/the-importance-of-technical-writing-and-typography-in-a-software-project/
|
||||
|
||||
I'm beginning to be more oriented on technical writing.
|
||||
In fact, I'm starting to consider to take on technical writing as a career.
|
||||
So I ask myself related to the very thing that makes me appreciate technical writing: documentation.
|
||||
That question is "What is effective documentation?"
|
||||
I'm beginning to be more oriented on technical writing.
|
||||
In fact, I'm starting to consider to take on technical writing as a career.
|
||||
So I ask myself related to the very thing that makes me appreciate technical writing: documentation.
|
||||
That question is "What is effective documentation?"
|
||||
|
||||
As I remember from https://www.youtube.com/watch?v=BAJ8F7yQz64[a presentation], there's this quote that rings very well.
|
||||
As I remember from https://www.youtube.com/watch?v=BAJ8F7yQz64[a presentation], there's this quote that rings very well.
|
||||
|
||||
[quote, Dan Allen, Antora: Documentation Sites for Software Teams]
|
||||
Documentation is the “curb appeal” of your software.
|
||||
Documentation is the “curb appeal” of your software.
|
||||
|
||||
Despite the saying, it applies to all types of projects.
|
||||
It is the "curb appeal" of your project.
|
||||
Despite the saying, it applies to all types of projects.
|
||||
It is the "curb appeal" of your project.
|
||||
|
||||
Let's take a shallow dive on the deep ocean of documentation and inspect what I think mainly builds it: technical writing and typography.
|
||||
Let's take a shallow dive on the deep ocean of documentation and inspect what I think mainly builds it: technical writing and typography.
|
||||
|
||||
|
||||
|
||||
|
||||
== Importance of technical writing
|
||||
== Importance of technical writing
|
||||
|
||||
Technical writing is an often-overlooked process for open source programs.
|
||||
This is reflected in https://opensourcesurvey.org/2017/[GitHub's 2017 survey on open source] (which is the latest version as of 2019-09-20) where incomplete and/or confusing documentation is the biggest hurdle.
|
||||
Technical writing is an often-overlooked process for open source programs.
|
||||
This is reflected in https://opensourcesurvey.org/2017/[GitHub's 2017 survey on open source] (which is the latest version as of 2019-09-20) where incomplete and/or confusing documentation is the biggest hurdle.
|
||||
|
||||
What's common among successful software projects like https://asciidoctor.org/[Asciidoctor], https://reactjs.org/[React], https://www.python.org/[Python], https://laravel.com/[Laravel], https://www.mozilla.org/en-US/firefox/[Firefox], https://www.latex-project.org/[LaTeX], https://www.google.com/chrome/browser/index.html[Chrome], and https://www.archlinux.org/[Arch Linux] is the accessible and thorough documentation that describes enough details for the new and the seasoned users.
|
||||
What's common among successful software projects like https://asciidoctor.org/[Asciidoctor], https://reactjs.org/[React], https://www.python.org/[Python], https://laravel.com/[Laravel], https://www.mozilla.org/en-US/firefox/[Firefox], https://www.latex-project.org/[LaTeX], https://www.google.com/chrome/browser/index.html[Chrome], and https://www.archlinux.org/[Arch Linux] is the accessible and thorough documentation that describes enough details for the new and the seasoned users.
|
||||
|
||||
As such, one of the leading importance of technical writing is **communication**.
|
||||
Without the work of technical writing means no communication.
|
||||
Non-existent communication means no incentive to look for your project.
|
||||
It's that simple.
|
||||
As such, one of the leading importance of technical writing is **communication**.
|
||||
Without the work of technical writing means no communication.
|
||||
Non-existent communication means no incentive to look for your project.
|
||||
It's that simple.
|
||||
|
||||
The documentation is where the first impression lies for your potential users.
|
||||
Despite the saying of judging the book by its cover, the documentation can reflect the quality of the project.
|
||||
Having non-existent or bad documentation gives the impression that your project is bad no matter how well-crafted or optimized your code.
|
||||
The documentation is where the first impression lies for your potential users.
|
||||
Despite the saying of judging the book by its cover, the documentation can reflect the quality of the project.
|
||||
Having non-existent or bad documentation gives the impression that your project is bad no matter how well-crafted or optimized your code.
|
||||
|
||||
The documentation is also where the lasting impression goes for the veterans and potential contributors.
|
||||
If the users see the project docs is working as intended and well-maintained then it's more likely for them to participate and contribute through bug issues and code improvements.
|
||||
The documentation is also where the lasting impression goes for the veterans and potential contributors.
|
||||
If the users see the project docs is working as intended and well-maintained then it's more likely for them to participate and contribute through bug issues and code improvements.
|
||||
|
||||
If you're learning another framework or a tool, odds are you would first visit the startup guide from their homepage.
|
||||
If you want to know more specific about the tool, you would dive further into their detailed sections.
|
||||
If you're learning another framework or a tool, odds are you would first visit the startup guide from their homepage.
|
||||
If you want to know more specific about the tool, you would dive further into their detailed sections.
|
||||
|
||||
If you want to get a shot at making your project to be recognized, give the documentation a priority.
|
||||
If you want to get a shot at making your project to be recognized, give the documentation a priority.
|
||||
|
||||
Like what I previously mentioned, this doesn't only apply to software projects but to all types of products whether it's a power tool, a phone, a calculator, or a book.
|
||||
Like what I previously mentioned, this doesn't only apply to software projects but to all types of products whether it's a power tool, a phone, a calculator, or a book.
|
||||
|
||||
* If you're opening up a package of your shiny new power tool, odds are you would need to get your hands on a manual.
|
||||
* If you've just received your new phone, you would find the user manual first to get started.
|
||||
* If you want to know all of the capabilities of your calculator, you might want to view the manual.
|
||||
* If you newly start with a referential book, you would explore first the preface or the introduction where it introduces the structure of each section.
|
||||
* If you're opening up a package of your shiny new power tool, odds are you would need to get your hands on a manual.
|
||||
* If you've just received your new phone, you would find the user manual first to get started.
|
||||
* If you want to know all of the capabilities of your calculator, you might want to view the manual.
|
||||
* If you newly start with a referential book, you would explore first the preface or the introduction where it introduces the structure of each section.
|
||||
|
||||
As you imagine, the use and importance of technical writing is everywhere.
|
||||
As you imagine, the use and importance of technical writing is everywhere.
|
||||
|
||||
Though, be wary that there is a flip side on technical writing.
|
||||
When there's communication, there's miscommunication.
|
||||
It can be blamed to various things but the point is having outdated or incorrect documentation can also give a bad impression.
|
||||
Worse is that it might be better to have no documentation at all.
|
||||
Though, be wary that there is a flip side on technical writing.
|
||||
When there's communication, there's miscommunication.
|
||||
It can be blamed to various things but the point is having outdated or incorrect documentation can also give a bad impression.
|
||||
Worse is that it might be better to have no documentation at all.
|
||||
|
||||
|
||||
|
||||
|
||||
== Importance of typography
|
||||
== Importance of typography
|
||||
|
||||
How about typography?
|
||||
It seems like it's a specific requirement for a software project but it can be important in making your content legible.
|
||||
No one in their right mind would read the content no matter how well-written if it's badly formatted.
|
||||
How about typography?
|
||||
It seems like it's a specific requirement for a software project but it can be important in making your content legible.
|
||||
No one in their right mind would read the content no matter how well-written if it's badly formatted.
|
||||
|
||||
Typography can boost the "curb appeal" further by adding greenery to your project.
|
||||
It makes all the more pleasing to the eyes.
|
||||
Typography can boost the "curb appeal" further by adding greenery to your project.
|
||||
It makes all the more pleasing to the eyes.
|
||||
|
||||
Typography also dictates how long will the user stay reading.
|
||||
A badly formatted book will surely receive shorter retention than a badly written one.
|
||||
It's a bonus if the reader will also get a laugh out of the badly written one.
|
||||
Typography also dictates how long will the user stay reading.
|
||||
A badly formatted book will surely receive shorter retention than a badly written one.
|
||||
It's a bonus if the reader will also get a laugh out of the badly written one.
|
||||
|
||||
|
||||
|
||||
|
||||
== Inspecting other projects
|
||||
== Inspecting other projects
|
||||
|
||||
They say that success and advancements stand on the shoulder of giants.
|
||||
Let's inspect how other software projects did their thing.
|
||||
They say that success and advancements stand on the shoulder of giants.
|
||||
Let's inspect how other software projects did their thing.
|
||||
|
||||
Think about most of the software you've used and remember your experience navigating the documentation.
|
||||
The million-dollar question is what's common between the documentations of popular projects and what good practices can we get from them.
|
||||
Think about most of the software you've used and remember your experience navigating the documentation.
|
||||
The million-dollar question is what's common between the documentations of popular projects and what good practices can we get from them.
|
||||
|
||||
To get us in the same page, here's the list of software I reflected and inspected:
|
||||
To get us in the same page, here's the list of software I reflected and inspected:
|
||||
|
||||
* https://www.archlinux.org/[Arch Linux]
|
||||
* https://asciidoctor.org/[Asciidoctor]
|
||||
* http://luatex.org/[LuaTeX]
|
||||
* https://www.ctan.org/pkg/latexmk/[Latexmk]
|
||||
* https://www.python.org/[Python]
|
||||
* https://reactjs.org/[ReactJS]
|
||||
* https://www.archlinux.org/[Arch Linux]
|
||||
* https://asciidoctor.org/[Asciidoctor]
|
||||
* http://luatex.org/[LuaTeX]
|
||||
* https://www.ctan.org/pkg/latexmk/[Latexmk]
|
||||
* https://www.python.org/[Python]
|
||||
* https://reactjs.org/[ReactJS]
|
||||
|
||||
Anyhow, I try to answer the million-dollar question.
|
||||
I put the answers in two lists: one for the content and one for the typography.
|
||||
Anyhow, I try to answer the million-dollar question.
|
||||
I put the answers in two lists: one for the content and one for the typography.
|
||||
|
||||
|
||||
=== Common attributes of documentation content
|
||||
=== Common attributes of documentation content
|
||||
|
||||
Here's what I gathered for reflecting the experience reading through the content.
|
||||
I've also observed how they organize their content and lead their users into the different parts of the program.
|
||||
Here's what I gathered for reflecting the experience reading through the content.
|
||||
I've also observed how they organize their content and lead their users into the different parts of the program.
|
||||
|
||||
* They provide examples.
|
||||
* They don't repeat information a lot and gives the appropriate link instead.
|
||||
* They organize the documents commonly by required level of expertise and general concepts.
|
||||
* Most of them (if not all) provide generalized explanations and a detailed version.
|
||||
* Not everything is documented compared to looking at the source, if available (e.g. https://www.python.org/[Python]).
|
||||
* They provide examples.
|
||||
* They don't repeat information a lot and gives the appropriate link instead.
|
||||
* They organize the documents commonly by required level of expertise and general concepts.
|
||||
* Most of them (if not all) provide generalized explanations and a detailed version.
|
||||
* Not everything is documented compared to looking at the source, if available (e.g., https://www.python.org/[Python]).
|
||||
|
||||
|
||||
=== Typographic best practices
|
||||
=== Typographic best practices
|
||||
|
||||
Here's one for navigating through the documentation and observing the typography.
|
||||
Here's one for navigating through the documentation and observing the typography.
|
||||
|
||||
* Optimal characters per line are at least 50 to 80.
|
||||
* Base font size is at least 16px.
|
||||
* Font size and spacing of headers of various levels are distinct.
|
||||
* Consistent use of brand colors (if there's any).
|
||||
* Use monospace font for code listings.
|
||||
* Optimal characters per line are at least 50 to 80.
|
||||
* Base font size is at least 16px.
|
||||
* Font size and spacing of headers of various levels are distinct.
|
||||
* Consistent use of brand colors (if there's any).
|
||||
* Use monospace font for code listings.
|
||||
|
||||
Regarding the best example, I think https://reactjs.org/docs/[React] does this the best both in documentation content and typographic practices.
|
||||
Go on, take a gander on it.
|
||||
Regarding the best example, I think https://reactjs.org/docs/[React] does this the best both in documentation content and typographic practices.
|
||||
Go on, take a gander on it.
|
||||
|
||||
.ReactJS documentation
|
||||
image::react-docs.webp[ReactJS docs]
|
||||
.ReactJS documentation
|
||||
image::images/react-docs.webp[ReactJS docs]
|
||||
|
||||
|
||||
|
||||
|
||||
== How I practice these?
|
||||
== How I practice these?
|
||||
|
||||
I won't detail much on how to practice technical writing or apply typographic practices since I'm not a professional.
|
||||
Instead, I'm describing how I apply the two skills.
|
||||
I won't detail much on how to practice technical writing or apply typographic practices since I'm not a professional.
|
||||
Instead, I'm describing how I apply the two skills.
|
||||
|
||||
|
||||
=== Plan the document early on the project
|
||||
=== Plan the document early on the project
|
||||
|
||||
To create good documentation, you must take the time to plan the document.
|
||||
Ask yourself what is the ideal document structure for your users, what information do they need to know, and other questions that reflect the value of efficient documentation.
|
||||
To create good documentation, you must take the time to plan the document.
|
||||
Ask yourself what is the ideal document structure for your users, what information do they need to know, and other questions that reflect the value of efficient documentation.
|
||||
|
||||
Even for a small project, making effort to plan is heavily appreciated.
|
||||
Even for a small project, making effort to plan is heavily appreciated.
|
||||
|
||||
In my case, I created a document structure for my project.
|
||||
Create a README and the `docs/` folder for assets (e.g. images, videos).
|
||||
I also created a standard template for my README: the abstract, purpose, getting started guide, details, and the license.
|
||||
You can see more of the details in my https://github.com/foo-dogsquared/personal-style-guides/blob/master/src/projects.adoc[project template documentation].
|
||||
In my case, I created a document structure for my project.
|
||||
Create a README and the `docs/` folder for assets (e.g., images, videos).
|
||||
I also created a standard template for my README: the abstract, purpose, getting started guide, details, and the license.
|
||||
You can see more of the details in my https://github.com/foo-dogsquared/personal-style-guides/blob/master/src/projects.adoc[project template documentation].
|
||||
|
||||
|
||||
=== Document only the big things
|
||||
=== Document only the big things
|
||||
|
||||
By that, I mean prioritize documenting the high-level details like the architecture, data design, implementations, and abstractions.
|
||||
You don't have to document your whole codebase (and you shouldn't).
|
||||
Leave out the very specific details and only draw the big picture.
|
||||
By that, I mean prioritize documenting the high-level details like the architecture, data design, implementations, and abstractions.
|
||||
You don't have to document your whole codebase (and you shouldn't).
|
||||
Leave out the very specific details and only draw the big picture.
|
||||
|
||||
When you did document the whole thing from its nooks and crannies, you give rise to another problem of constantly switching gears for updating your code and the documentation.
|
||||
It's a nasty experience that you might as well not document it in the first place.
|
||||
When you did document the whole thing from its nooks and crannies, you give rise to another problem of constantly switching gears for updating your code and the documentation.
|
||||
It's a nasty experience that you might as well not document it in the first place.
|
||||
|
||||
|
||||
=== Create a minimal design that focuses on readability
|
||||
|
||||
For practicing typography, you can create a minimalistic design that focuses on content form.
|
||||
For practicing typography, you can create a minimalistic design that focuses on content form.
|
||||
|
||||
In my case, I recently started to refer to https://practicaltypography.com/[some] https://zellwk.com/blog/why-vertical-rhythms/[related] https://www.paulolyslager.com/optimal-text-layout-line-length/[resources] and quickly created a https://github.com/foo-dogsquared/hugo-theme-contentful[Hugo theme that focuses on it].
|
||||
In my case, I recently started to refer to https://practicaltypography.com/[some] https://zellwk.com/blog/why-vertical-rhythms/[related] https://www.paulolyslager.com/optimal-text-layout-line-length/[resources] and quickly created a https://github.com/foo-dogsquared/hugo-theme-contentful[Hugo theme that focuses on it].
|
||||
|
||||
.Here's the resulting Hugo theme - Contentful
|
||||
image::hugo-theme-contentful.webp[.Hugo theme Contentful]
|
||||
image::images/hugo-theme-contentful.webp[.Hugo theme Contentful]
|
||||
|
||||
You could also start by redesigning some of your previous stuff.
|
||||
You could also start by redesigning some of your previous stuff.
|
||||
|
||||
I've started to reconfigure my LaTeX templates and it is certainly more readable than before.
|
||||
I've started to reconfigure my LaTeX templates and it is certainly more readable than before.
|
||||
footnote:[My LaTeX templates can be found at https://github.com/foo-dogsquared/latex-templates/[my GitHub account].]
|
||||
|
||||
.My current LaTeX lecture layout
|
||||
image::latex-lecture-layout.webp[alt="My current LaTeX lecture layout", width=450]
|
||||
image::images/latex-lecture-layout.webp[alt="My current LaTeX lecture layout", width=450]
|
||||
|
||||
It has improved spacing between paragraphs and non-textblocks, larger font sizes for mathematical texts, and improved font combinations.
|
||||
It has improved spacing between paragraphs and non-textblocks, larger font sizes for mathematical texts, and improved font combinations.
|
||||
footnote:[If you're curious about the font combination, it uses https://github.com/adobe-fonts/source-serif-pro[Source Serif Pro] for roman (normal), https://github.com/adobe-fonts/source-sans-pro[Source Sans Pro] for sans, and https://github.com/tonsky/FiraCode[Fira Code] for monospace.]
|
||||
|
||||
|
||||
=== Create a style guide or a set of guidelines
|
||||
|
||||
Style guides are used to keep certain aspects of a project to be consistent.
|
||||
Certain examples exist on styling your code, general writing, academic writing, citations, design, technical writing, and many others.
|
||||
Style guides are used to keep certain aspects of a project to be consistent.
|
||||
Certain examples exist on styling your code, general writing, academic writing, citations, design, technical writing, and many others.
|
||||
footnote:[You can see examples of them at my https://github.com/foo-dogsquared/personal-style-guides[personal style guides README].]
|
||||
|
||||
However, all (if not most) style guides are suited for the organization's purposes.
|
||||
If you aren't able to find a suitable one, just create one.
|
||||
It doesn't have to cover every possible case since it is specifically created for your own (or your team).
|
||||
You can steal ideas from multiple style guides, cherry-pick the best of them, and combine it to suit your specific needs.
|
||||
However, all (if not most) style guides are suited for the organization's purposes.
|
||||
If you aren't able to find a suitable one, just create one.
|
||||
It doesn't have to cover every possible case since it is specifically created for your own (or your team).
|
||||
You can steal ideas from multiple style guides, cherry-pick the best of them, and combine it to suit your specific needs.
|
||||
|
||||
In my case, I created a writing style guide that generally applies to all of my writing and typography works.
|
||||
I eventually dedicated https://github.com/foo-dogsquared/personal-style-guides[a repo for my guide styles] to easily refer to it in the future.
|
||||
In my case, I created a writing style guide that generally applies to all of my writing and typography works.
|
||||
I eventually dedicated https://github.com/foo-dogsquared/personal-style-guides[a repo for my guide styles] to easily refer to it in the future.
|
||||
|
||||
|
||||
|
||||
|
||||
== Conclusion
|
||||
== Conclusion
|
||||
|
||||
The documentation is a powerful tool for projects.
|
||||
They serve as an introduction and make the "curb appeal" for your project.
|
||||
Practicing technical writing can amp up your communication skills which can mean the make-or-break moment for your project.
|
||||
The documentation is a powerful tool for projects.
|
||||
They serve as an introduction and make the "curb appeal" for your project.
|
||||
Practicing technical writing can amp up your communication skills which can mean the make-or-break moment for your project.
|
||||
|
||||
In any case, technical writing must also be presentable.
|
||||
Your documentation may have all of the content they need to know but nobody is going to read good content with bad form.
|
||||
Typography can help you out in making your content legible and easy to read.
|
||||
Applying related typography practices can make cruising through the documentation a pleasant experience.
|
||||
In any case, technical writing must also be presentable.
|
||||
Your documentation may have all of the content they need to know but nobody is going to read good content with bad form.
|
||||
Typography can help you out in making your content legible and easy to read.
|
||||
Applying related typography practices can make cruising through the documentation a pleasant experience.
|
||||
|
||||
Giving some time for technical writing and typography can surely boost the impression of your project.
|
||||
It also adds the bonus of future-proofing your project for yourself and for others.
|
||||
Giving some time for technical writing and typography can surely boost the impression of your project.
|
||||
It also adds the bonus of future-proofing your project for yourself and for others.
|
||||
|
||||
|
||||
|
||||
|
||||
== Further looking
|
||||
== Further looking
|
||||
|
||||
|
||||
=== Books
|
||||
=== Books
|
||||
|
||||
https://openoregon.pressbooks.pub/aboutwriting/[_About Writing: A Guide_ by "Open Oregon Press"]::
|
||||
An open textbook that describes the process of writing for different papers.
|
||||
It also gives tips on writing a sufficient body of text that can apply for various papers like academic and research papers.
|
||||
An open textbook that describes the process of writing for different papers.
|
||||
It also gives tips on writing a sufficient body of text that can apply for various papers like academic and research papers.
|
||||
|
||||
https://practicaltypography.com/[_Practical Typography_ by "Matthew Butterick"]::
|
||||
A pay-as-you-want online book that introduces you to typography with practical lessons and descriptions.
|
||||
I fully recommend this book if you want to learn more about how to make your content presentable.
|
||||
https://practicaltypography.com/[_Practical Typography_ by "Matthew Butterick"]::
|
||||
A pay-as-you-want online book that introduces you to typography with practical lessons and descriptions.
|
||||
I fully recommend this book if you want to learn more about how to make your content presentable.
|
||||
|
||||
https://openoregon.pressbooks.pub/technicalwriting/[_Technical Writing_ by "Open Oregon Press"]::
|
||||
Another open textbook from the https://openoregon.pressbooks.pub/[Open Oregon Press] that specifically tackles technical writing of various formats from emails, cover letters, and résumé.
|
||||
This covers the basics you need to get started on practicing efficient technical writing.
|
||||
Another open textbook from the https://openoregon.pressbooks.pub/[Open Oregon Press] that specifically tackles technical writing of various formats from emails, cover letters, and résumé.
|
||||
This covers the basics you need to get started on practicing efficient technical writing.
|
||||
|
||||
|
||||
=== Tools
|
||||
=== Tools
|
||||
|
||||
https://asciidoctor.org/[Asciidoctor]::
|
||||
An Asciidoc-based toolchain for publishing documents into various output formats.
|
||||
It also expanded upon the original http://asciidoc.org/[Asciidoc] markup language with additional text formatting features.
|
||||
It's what I mainly use for writing documentation for my projects.
|
||||
https://asciidoctor.org/[Asciidoctor]::
|
||||
An Asciidoc-based toolchain for publishing documents into various output formats.
|
||||
It also expanded upon the original http://asciidoc.org/[Asciidoc] markup language with additional text formatting features.
|
||||
It's what I mainly use for writing documentation for my projects.
|
||||
|
||||
|
||||
=== Web
|
||||
=== Web
|
||||
|
||||
https://github.com/noffle/art-of-readme[_Art of README_ by "noffle"]::
|
||||
It's a GitHub repo detailing on READMEs from what they are to what makes them good.
|
||||
https://github.com/noffle/art-of-readme[_Art of README_ by "noffle"]::
|
||||
It's a GitHub repo detailing on READMEs from what they are to what makes them good.
|
||||
|
||||
https://www.instructionalsolutions.com/blog/become-a-technical-writer[_How to Become a Technical Writer: A Beginner’s Guide_ by "Tom DuPuis"]::
|
||||
An overview for absolute beginners for those who are looking into technical writing.
|
||||
Tackles various topics that you should know first and foremost.
|
||||
https://www.instructionalsolutions.com/blog/become-a-technical-writer[_How to Become a Technical Writer: A Beginner’s Guide_ by "Tom DuPuis"]::
|
||||
An overview for absolute beginners for those who are looking into technical writing.
|
||||
Tackles various topics that you should know first and foremost.
|
||||
|
||||
https://www.writethedocs.org/[Write the Docs]::
|
||||
A global community of people who cares about writing documentation.
|
||||
They provide good resources for getting started with technical writing on the website.
|
||||
https://www.writethedocs.org/[Write the Docs]::
|
||||
A global community of people who cares about writing documentation.
|
||||
They provide good resources for getting started with technical writing on the website.
|
||||
|
@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Projects"
|
||||
---
|
||||
|
||||
Here's where I discuss my projects in detail from its
|
||||
overview, design, implementations, and notes I took while
|
||||
creating the project.
|
9
go.mod
Normal file
@ -0,0 +1,9 @@
|
||||
module github.com/foo-dogsquared/blog
|
||||
|
||||
go 1.15
|
||||
|
||||
require (
|
||||
github.com/foo-dogsquared/hugo-theme-more-contentful v0.1.2 // indirect
|
||||
github.com/foo-dogsquared/hugo-web-feeds v0.0.1 // indirect
|
||||
github.com/simple-icons/simple-icons v0.0.0-20201025110046-413f781fd706 // indirect
|
||||
)
|
11
go.sum
Normal file
@ -0,0 +1,11 @@
|
||||
github.com/foo-dogsquared/hugo-mod-simple-icons v0.0.0-20201026173406-633714bb359d/go.mod h1:IqgEwYyo2L3mFR2RoelZZ3Ncwph7QTssrZ3deCaE0us=
|
||||
github.com/foo-dogsquared/hugo-theme-contentful v1.2.1-0.20201030114530-c0a2488a58fb/go.mod h1:BL7L5CENEhUx+miRRaOZ9SVC92j9MAMztirBWtTpiPc=
|
||||
github.com/foo-dogsquared/hugo-theme-more-contentful v0.1.1 h1:34Ey7ysM769d8Lf2hOrTLSL5v7JpGnQyhk5NglRAP+4=
|
||||
github.com/foo-dogsquared/hugo-theme-more-contentful v0.1.1/go.mod h1:rt3VJjkzt/dXRcVk8wNacnyDQfy9DwOYI45FAu4I9mw=
|
||||
github.com/foo-dogsquared/hugo-theme-more-contentful v0.1.2 h1:liGphVux817iNxviDkdBLTzMXj9qkNENkNR7kUXG09A=
|
||||
github.com/foo-dogsquared/hugo-theme-more-contentful v0.1.2/go.mod h1:rt3VJjkzt/dXRcVk8wNacnyDQfy9DwOYI45FAu4I9mw=
|
||||
github.com/foo-dogsquared/hugo-web-feeds v0.0.1 h1:miuJMx2Plw+4TBGctI2CgWXilddEHFnKNDQ9kLNti3w=
|
||||
github.com/foo-dogsquared/hugo-web-feeds v0.0.1/go.mod h1:0WxK3+xNIj/Wpk2kkUW0p6Uqmr/OZjPsRtQDCMazNmI=
|
||||
github.com/refactoringui/heroicons v0.4.2/go.mod h1:82HsLWQga7MkEl5aK8TctxPPIBlXrsyWcVTB57uipuk=
|
||||
github.com/simple-icons/simple-icons v0.0.0-20201025110046-413f781fd706 h1:dXop39uj0JjYZqKfD2t8URe2CcmafSMnnX2ReK2/0J8=
|
||||
github.com/simple-icons/simple-icons v0.0.0-20201025110046-413f781fd706/go.mod h1:oOgUUt8yVYOso/wEBi2ojfZP2MU/xxiNccIpaE+jCvE=
|