Documentation clean up

1

Hello. I’ve adopted Zola for my website and I really enjoy using it. I’d like to give back to the project by improving the documention. I’ve noticed some inconsistencies and small mistakes (I work in editing, can’t help it). For example, “passing a other value” -> “passing another value”.

  1. I’ve forked the project in Github but I’m not sure how to best structure the patches. One patch per section (e.g., Getting Started)? Per subsection (e.g., CLI usage)?

  2. Would it be helpful to have some simple documentation guidelines? For example, regarding US/British spelling, Oxford comma, consistent terminology (e.g., directory/folder), etc.

  3. What is the best place to ask questions regarding certain sections of text. For example, “CLI usage” includes “Any of the three commands will emit colored output …”, but no commands are given (environment variables are mentioned).

Any input is appreciated.

2 Likes
2

Whoa thanks a lot for that!

  1. I think you can just do it in one patch (work on the next branch to avoid conflicts if you will have changes across the documentation). Make sure you don’t touch anything in zola/docs/content/themes at master · getzola/zola · GitHub as this is auto-generated from the themes README so it would just get overwritten.

  2. Good point. I use British spelling myself but since a good chunk of the documentation comes from people all over the world it’s hard to be consistent. I think the Oxford comma could confuse non-native English speaks like myself though, it definitely looks wrong to me :confused: We can definitely agree on a consistent terminology and stick with it though.

  3. We can do it in this thread, that’s the closest thing to a chat for Zola!

3

  1. I’ll first send a patch that fixes obvious mistakes. I’ll then send another patch for unclear text after we agree on meaning.

  2. I’ll apply British spelling throughout. I work with technical documentation (engineering research) and most guidelines for such text require the Oxford comma. But since you don’t like it, let’s leave it out :slight_smile: For terminology, I’ll keep a list and then include it in the guidelines.

  3. Sure, I’ll ask here. Another thing worth doing (I’ll volunteer) is making a small tutorial (e.g., basic blog) to get new users familiar with Zola concepts. I came to Zola after some experience with Pelican, Lektor, Hugo, and Django, so I had a good idea of how projects are set up. New users might need some help getting an overview. Django has excellent documentation (Django documentation | Django documentation | Django) that makes it easy to get started.

1 Like
4

  1. If you say it is something required in technical documentation maybe it’s worth having it. Do you know a good resource to learn where to use it?

  2. Yes, a quickstart is definitely needed! @HugoTrentesaux wrote one https://github.com/getzola/zola/issues/534#issuecomment-551065726 it would be worth checking if it ticks the same boxes you wanted for a quickstart.

As an aside, feel free to reorganize the documentation if you feel some sections should be split/merged. Content has been added for new features but quite a few people mentioned having issues finding what they are looking for in it and I am very blind to that since I don’t really use the documentation myself.

1 Like
5
  1. I’m mostly referring to author guidelines for engineering journals. One example is http://ieeeauthorcenter.ieee.org/wp-content/uploads/Transactions-instructions-only.pdf (IEEE = The Institute of Electrical and Electronics Engineers ). They mention:
    The serial comma is preferred: “A, B, and C” instead of “A, B and C.”

The existence or absence of the comma is not really important. It’s consistency that matters. I’m ok without it (even though I prefer it).

  1. That quickstart looks pretty good. I’ll contact the author when I’m done with the main docs.

Regarding reorganizing content, I think that’s a bit down the road. I’m thinking:
Phase 1: Fix obvious mistakes.
Phase 2: Clarify any parts that might be confusing.
Phase 3: Add quickstart.
Phase 4: Check forum for frequent questions and try to answer them in docs.
Phase 5: Reorganize.

I’ve only finished “Getting Started” for phase 1, so I’m going to stop making plans and get to work :slight_smile:

1 Like
6

For reference, this is the Django documentation writing guide:

https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/

7

Sounds perfect. Make sure you work on the next branch as I think there are already some changes to the doc in it

9

The PR is now the full documentation (still learning how github works).

10

Having read the full documentation, I now have a good idea of what is missing. I’ll slowly add content as I clarify the sections. The first missing information is just a general description of Zola for people not familiar with SSGs. I’ll copy part of a new “Overview” subsection I’m writing for the “Getting Starting” section. Let me know what you think (I had to remove the links for this post; links in ).

Zola at a Glance

Zola is a static site generator (SSG), similar to [Hugo], [Pelican], and [Jekyll] (for a comprehensive list of SSGs, please see the [StaticGen] site). It is written in [Rust] and uses the [Tera] template engine, which is similar to [Jinja2], [Django templates], [Liquid], and [Twig]. Content is written in [Markdown].

SSGs use dynamic templates to transform content into static HTML pages. Static sites are thus very fast and require no databases, making them easy to host. A comparison between static and dynamic sites, such as WordPress, Drupal, and Django, can be found [here].

If you are new to SSGs, please see the quick tutorial below.

First Steps with Zola

Unlike some SSGs, Zola makes no assumptions regarding the structure of your site. For this tutorial, we’ll be making a simple blog site.

Initialize Site

This tutorial is based on Zola 0.9.

Please see the detailed [installation instructions for your platform]. With Zola installed, let’s initialize our site:

$ zola init myblog

You will be asked a few questions.

> What is the URL of your site? (https://example.com):
> Do you want to enable Sass compilation? [Y/n]:
> Do you want to enable syntax highlighting? [y/N]:
> Do you want to build a search index of the content? [y/N]:

For our blog, let’s accept the default values (i.e., press Enter for each question). We now have a myblog directory with the following structure:

├── config.toml
├── content
├── sass
├── static
├── templates
└── themes

Let’s start the zola development server with:

$ zola serve
Building site...
-> Creating 0 pages (0 orphan), 0 sections, and processing 0 images

This command must be run in the base Zola directory, which contains config.toml.

If you point your web browser to [127.0.0.1:1111], you should see a “Welcome to Zola” message.

2 Likes