Documentation #148

dpordomingo · 2017-10-31T12:44:06Z

closes: #90 , #102 , #124 , #143 , https://github.com/src-d/backlog/issues/1058

The important changes are defined by:

The README.md has been polished
The contribution guides can be viewed at the CONTRIBUTING.md
The shortcode documentation can be biewed at shortcodes blog documentation post

The previous commits prepares the blog repository to be "documentable" ;)
Most important changes that has been done (and documented), are:

make serve will locally serve the blog -> wiiiiiiiii
authors are now stored under data/authors.yml file
all posts must be stored under contents/post (no longer upcoming)
post that should not yet being published, must be marked as draft: true

erizocosmico

Great job! Just some minor grammatical corrections

erizocosmico · 2017-10-31T13:03:19Z

CONTRIBUTING.md

+
+While you are developing or creating new contents for the blog, and always before publishing a PR, you should validate your changes locally, specially if you're modifying common features or you're using shortcodes.
+
+To locally serve the blog, you need to satisfy the [project requirements](README.md#requirements), and then to run:


s/then to run/then run/

erizocosmico · 2017-10-31T13:03:48Z

CONTRIBUTING.md

+```shell
+make serve;
+```
+and then, go to [http://localhost:8484](http://localhost:8484)


s/and then/Finally/

erizocosmico · 2017-10-31T13:05:01Z

CONTRIBUTING.md

+
+```
+---
+author: authorKeyName


also worth to mention that if it's the first time a user is posting on the blog, they should add themselves to the config file with all their data

erizocosmico · 2017-10-31T13:05:46Z

CONTRIBUTING.md

+
+### Front matter
+
+The **front matter** is the first section inside the content file &ndash;enclosed by "`---`" chars&ndash; where it is defined the content metadata.<br />(Read more about it in the Hugo docs for the [Front Matter section](https://gohugo.io/content-management/front-matter))


s/where it is defined the content metadata/where the content metadata is defined/

erizocosmico · 2017-10-31T13:06:33Z

CONTRIBUTING.md

+- `author`: Defines the authorship as explained in the [authors section](#authors)
+- `date`: Date when you plan to publish the post, `2006-01-02` format. **Do not forget to update it before publishing it.**
+- `title`: Post title, as it will appear in the very top of the content
+- `image`: Defines the content listing image as explained in the [assets section](#assets)


s/Defines the content listing image/Defines the image that will be shown in the list of posts/

erizocosmico · 2017-10-31T13:20:59Z

content/documentation/shortcodes.md

+For the caption of the image, it can be used html, markdown and other shortcodes
+
+```
+{{%/* caption src="//url-to-the-omage" title="title of image" %}}


why does it start with /*?

since the documentation has been written in a post entry (to use the hugo engine to generate the real display for the examples), the only way I found to avoid hugo to parse the shortcodes source code was introducing them inside comments:

{{%/* caption %}} This shortcode is not parsed as a shortcode {{% /caption */%}}

That way it can be properly rendered:

erizocosmico · 2017-10-31T13:21:11Z

content/documentation/shortcodes.md

+```
+{{%/* caption src="//url-to-the-omage" title="title of image" %}}
+caption of the image
+{{% /caption */%}}


why does it end with */?

as explained by #148 (comment)

erizocosmico · 2017-10-31T13:23:08Z

content/documentation/shortcodes.md

+
+## codepen
+
+Whenever it is needed to display something runnable like a demo, an example or a proof of concept, it should be used inside an embedded `codepen` snippet.


s/Whenever it is needed to display something runnable like a demo/Whenever displaying something runnable like a demo is needed/

Better as:

Whenever necessary to display content that includes runnable code, like a demo, notebook, an example or a proof of concept, it should be used inside an embedded codepen snippet.

erizocosmico · 2017-10-31T13:23:29Z

content/documentation/shortcodes.md

+{{%/* codepen slug="SLUG" title="TITLE" height="400" */%}}
+```
+
+The parameters that the `codepen` shortcode accepts are:


s/that the/the/

erizocosmico · 2017-10-31T13:24:37Z

content/documentation/shortcodes.md

+
+Display a Gist (even an IPython Notebook)
+
+If the gist if too height, you can use a `scroll-panel` shortcode to wrap it inside a scollable window.


s/if too height/is too big/

bzz · 2017-10-31T13:32:46Z

README.md

-{{% gist username gist_id %}}
+```shell
+make build;
 ```


It's really easy to install and build now!

Do you think we could add make serve line here as well? and http://localhost:8484 would be useful.

It's natural next step to look at it after building and would be nice if users could refresh their memory without "switching the context" and going to any other place

Thanks for the feedback @bzz
When you said

"Could you add make serve line here? [...]"

You say so to avoid opening the CONTRIBUTING.md where it is said (here), right?

If so, yes: I can add it to the README.md to have it as a quick hint.

You will find it at f45e5a5

vmarkovtsev · 2017-10-31T13:52:08Z

@dpordomingo Regarding archive, I put there posts published on other sites, e.g. the post on habrahabr.ru in Russian. It is never supposed to be visible in our blog yet there is no place where to put such stuff.

bzz · 2017-10-31T13:53:57Z

CONTRIBUTING.md

+
+Posts are stored under [`post` content directory](content/post)
+
+A blog post content stored under: `content/post/__POST_FILE_NAME__.md`


These two lines might make user think that content and post are something different.

How about changing it to something like

To create a new blog post, create new a file under `content/post/__POST_FILE_NAME__.md` using the following content schema.

vmarkovtsev · 2017-10-31T13:58:49Z

content/post/github_topic_modeling_habrahabr.md

@@ -1,4 +1,13 @@
-![word cloud](http://blog.sourced.tech/post/github_topic_modeling/wordcloud.png)
+---
+author: vadim


Yep, this is what I was talking about - we do not want to show this old russian post on habrahabr

bzz · 2017-10-31T14:04:50Z

Great job @dpordomingo !! Thank you so much for proving clear instructions on using blog.
It also has super-nice experience of live edits!

Probably a nit, but after trying it locally I only was wondering if yarn.lock intentionally not in .gitignore? As somebody might commit it.

Otherwise its 🏎

erizocosmico · 2017-10-31T14:42:37Z

@bzz yarn.lock is intended to be committed.

ricardobaeta

Awesome work @dpordomingo !

I'll give it a try soon(ish) and document any doubts or errors.

Thanks!

marnovo

Reviewed. Suggestions/changes/questions added. Overall looking very good!

marnovo · 2017-10-31T14:48:05Z

CONTRIBUTING.md

+- `title`: Post title, as it will appear in the very top of the content
+- `image`: Defines the content listing image as explained in the [assets section](#assets)
+- `description`: Short description of the post. Plain text only; no HTML nor markdown allowed.
+- `categories`: An array of at least one of the following: `science`, `technical`, `culture`. If it is not defined, it will not be served by the json blog api, so it will not appear in the source{d} landing.


What is the sciencecategory about? We currently show in the landing just technical and culture, right?

Yes, we only show technical and culture posts.
If you want to drop the science category, already applied to all the ML posts, we should address it via a separated issue, shouldn't we? ;)

marnovo · 2017-10-31T15:03:50Z

CONTRIBUTING.md

+
+### Formatting the content
+
+It is not allowed to use HTML tags to format the content of the blog.


Better as:

It is strictly forbidden to use HTML tags and/or custom to format the content of the blog. These add unnecessary complexity to the blog maintenance and will eventually break in layout changes.

You could even further add:

Offenders will be shot; Survivors will be shot again.

marnovo · 2017-10-31T15:08:55Z

CONTRIBUTING.md

+
+It is not allowed to use HTML tags to format the content of the blog.
+
+If you want/need special formatting for your content, please read the [shortcodes tutorial](https://blog.sourced.tech/documentation/shortcodes)


Better as:

If you believe your content really requires a feature that is not currently supported by the current shortcodes, please check the issues and create a feature request. The product owner will evaluate feasibility and the benefit to all users before approving implementation.

marnovo · 2017-10-31T15:18:20Z

CONTRIBUTING.md

+
+## Peer review
+
+Validate every new contents with [a PR](https://github.com/src-d/blog/pulls), that will be validated by, at least:


Better as:

New content must be validated via a PR, by at least both:

vmarkovtsev on the content;

platform on the layout.

marnovo · 2017-10-31T15:20:41Z

README.md

-  (for a sourced pen, the url looks like codepen.io/sourced/pen/slug).
- `user` (_optional_, defaults to sourced) the user in codepen.
- `title`(_optional_, defaults to sourced) a title for the codepen.
+Copyright (c) 2015 Máximo Cuadros, see [LICENSE](LICENSE)


marnovo · 2017-10-31T15:57:23Z

content/documentation/shortcodes.md

+
+## codepen
+
+Whenever it is needed to display something runnable like a demo, an example or a proof of concept, it should be used inside an embedded `codepen` snippet.


Better as:

Whenever necessary to display content that includes runnable code, like a demo, notebook, an example or a proof of concept, it should be used inside an embedded codepen snippet.

marnovo · 2017-10-31T16:13:58Z

README.md

-This is our [blog](https://blog.sourced.tech) source. It uses fancy technologies, such as:
- [Hugo](http://gohugo.io/)
- [Caddy](https://caddyserver.com/)
+This is our [blog](https://blog.sourced.tech) source.


This is the repository for the source{d} blog, which generates styled static HTML from markdown files.

If you came here to learn how to set up the blog in your computer, to write/preview/deploy a new blog post, you should check:

Blog setup requirements and Build

How to contribute

marnovo · 2017-10-31T16:16:21Z

README.md

-### Gist
-
-Display a Gist (even an IPython Notebook)
+You need to satisfy the [project requirements](#requirements), and then to run:


You have to run that the project root dir, right?

Also we must make clearer what does it mean/happens when you build it.

marnovo · 2017-10-31T16:17:14Z

README.md

-```
-{{% codepen slug="aaaaaa" title="My post example" %}}
-```
+If you want to contribute to this project, you will find more info in the [CONTRIBUTING.md](CONTRIBUTING.md)


If you want to contribute to this project, or to write or edit a blog post, you will find more info in the contribution guidelines.

marnovo · 2017-10-31T16:18:57Z

README.md

-### YouTube video
+The blog also uses:
+- [Hugo](http://gohugo.io): to build the static html from the markdown content files; it is automatically downloaded and installed at building time.
+- [Caddy](https://caddyserver.com): to serve the static files in production; it is provided by the caddy docker image


Can these be any version? Any additional steps people have to do after installing them in their system?

No additional steps. As it is said for each of one of them, they are provided at build stage or by the docker image.
They're listed here to let the developer to know in which context the blog will run.

dpordomingo · 2017-10-31T20:14:55Z

Ok @vmarkovtsev Let's see how can I handle the "habrahabr" feature

dpordomingo · 2017-10-31T21:03:54Z

Thanks for your awesome review folks!!!

@rporres I added the flag into the make serve as we agreed
53531d1

@bzz @marnovo @erizocosmico I considered your requests in the new commits:

REVIEW. Alex to the README.md for 'make serve' dev rule
e8315bb
REVIEW. Marcelo and Miguel to the docs 762b072

@vmarkovtsev upcoming/id2vec was redirected to staging, and habrahabr post was restored

Redirect id2vec to staging till has been released e35e25c
Restore habrahabr under its original path https://blog-staging.srcd.run/archive/github_topic_modeling_habrahabr/ a193e64

marnovo

🚀

bzz

dpordomingo · 2017-11-02T11:49:39Z

Many Thank you all for your deep review!
@erizocosmico @vmarkovtsev Does my changes satisfies your requirements?

bzz · 2017-11-03T11:24:40Z

Just FYI @erizocosmico is on vacation

dpordomingo · 2017-11-03T11:35:55Z

Sure. Just waiting ;)

dpordomingo mentioned this pull request Oct 31, 2017

[WIP] Document the blog #145

Closed

dpordomingo requested review from erizocosmico, vmarkovtsev and marnovo October 31, 2017 12:49

dpordomingo mentioned this pull request Oct 31, 2017

Fixes #149

Merged

erizocosmico suggested changes Oct 31, 2017

View reviewed changes

bzz reviewed Oct 31, 2017

View reviewed changes

vmarkovtsev suggested changes Oct 31, 2017

View reviewed changes

dpordomingo mentioned this pull request Oct 31, 2017

Use webpack to build assets #146

Merged

ricardobaeta reviewed Oct 31, 2017

View reviewed changes

marnovo requested changes Oct 31, 2017

View reviewed changes

dpordomingo mentioned this pull request Oct 31, 2017

Considering a blog relicensing #151

Closed

dpordomingo force-pushed the documentation branch from eea4f5d to 59e540c Compare October 31, 2017 20:57

dpordomingo changed the base branch from master to release/v1.1 October 31, 2017 21:04

dpordomingo force-pushed the documentation branch from 59e540c to a193e64 Compare October 31, 2017 21:37

marnovo approved these changes Oct 31, 2017

View reviewed changes

bzz approved these changes Nov 2, 2017

View reviewed changes

erizocosmico approved these changes Nov 7, 2017

View reviewed changes

dpordomingo added 3 commits November 8, 2017 07:15

Use webpack in blog build stage and remove autogenerated

e7ff673

Move layouts from root to theme

3962a14

Use a common skeleton for list and single layouts

9cf17fd

dpordomingo added 8 commits November 8, 2017 07:16

Move custom code.css from theme to src/css/entry.css

e190092

Rearrange assets

38acf20

Remove draft:false from contents because it is its default value

c105bf2

Use relative links to internal post links

073dfb6

Move 'authors' definitions into 'data' files

6516f06

Move 'pseudodrafts' into 'post' dir and label them as 'real draft'

f9550d3

Redirect id2vec to staging till has been released

dd12e1a

Document the Blog

5978368

dpordomingo force-pushed the documentation branch from a193e64 to 5978368 Compare November 8, 2017 06:16

dpordomingo merged commit 9ccc989 into src-d:release/v1.1 Nov 8, 2017

dpordomingo deleted the documentation branch November 8, 2017 06:21

This was referenced Nov 8, 2017

Release/v1.1 #154

Merged

Relicense blog under source{d} #158

Merged


		While you are developing or creating new contents for the blog, and always before publishing a PR, you should validate your changes locally, specially if you're modifying common features or you're using shortcodes.

		To locally serve the blog, you need to satisfy the [project requirements](README.md#requirements), and then to run:


		### Front matter

		The front matter is the first section inside the content file –enclosed by "`---`" chars– where it is defined the content metadata.<br />(Read more about it in the Hugo docs for the [Front Matter section](https://gohugo.io/content-management/front-matter))


		## codepen

		Whenever it is needed to display something runnable like a demo, an example or a proof of concept, it should be used inside an embedded `codepen` snippet.


		Display a Gist (even an IPython Notebook)

		If the gist if too height, you can use a `scroll-panel` shortcode to wrap it inside a scollable window.


		Posts are stored under [`post` content directory](content/post)

		A blog post content stored under: `content/post/__POST_FILE_NAME__.md`


		### Formatting the content

		It is not allowed to use HTML tags to format the content of the blog.


		It is not allowed to use HTML tags to format the content of the blog.

		If you want/need special formatting for your content, please read the [shortcodes tutorial](https://blog.sourced.tech/documentation/shortcodes)


		## Peer review

		Validate every new contents with [a PR](https://github.com/src-d/blog/pulls), that will be validated by, at least:

Documentation #148

Documentation #148

Uh oh!

Conversation

dpordomingo commented Oct 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

erizocosmico left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bzz Oct 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vmarkovtsev commented Oct 31, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bzz commented Oct 31, 2017

Uh oh!

erizocosmico commented Oct 31, 2017

Uh oh!

ricardobaeta left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marnovo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

dpordomingo commented Oct 31, 2017 •

edited

Loading

bzz Oct 31, 2017 •

edited

Loading

ricardobaeta left a comment •

edited

Loading

dpordomingo commented Oct 31, 2017 •

edited

Loading