Announcing Ziggit Docs

Site Feedback
1

We are pleased and excited to announce a new initiative for the Zig community and Ziggit in particular. We call it Ziggit Docs (or Docs for short) and it’s a way for the community to actively create and maintain a kind of live documentation or reference material for all things related to Zig.

Overview

  1. Ziggit community members who regularly participate on the forum can create new topics to be included in Docs.

  2. Docs topics can be edited by the community. New topics in the Docs category are set to Wiki mode by default which allows other users to edit their content, just like in Wikipedia! This enables collaboration towards building a community-driven corpus of documentation.

  3. The community can also reply to Docs topics. Replies are helpful for expressing ideas that can’t be directly communicated via editing the topic. Replies can also be used to publicly propose changes.

  4. The Docs system is structured via tags. Selecting a proper tag (or set of tags) is important to ensure effective reach through link navigation and the search interface. We’ve created a few topics already that can serve as examples of what’s possible.

How To Find Ziggit Docs

There are two entry points:

  • The Docs user interface (UI) for everyone to browse, search, filter, and read the content. This is found at https://ziggit.dev/docs. You can find a link in the top navigation and by clicking More to expand the links in the left navigation sidebar. [1]

  • The Docs category where community members who regularly participate in the Ziggit forum can create new topics to be included in the Docs system.

Ziggit Docs Content Guidelines

  1. Please consider whether your topic serves as documentation or if it belongs in a more open-ended category of the forum.

  2. Try to teach with both examples and explanations. Code examples should be approachable with clear and concise explanations.

  3. Docs should be Zig focused. Ziggit Docs is not intended to be a repository for general computer science and programming information outside the scope of Zig.

We welcome you to the Docs authoring community and thank you for contributing!

  1. If you don’t see the links, you may need to reload the page in your browser. ↩︎

27 Likes
3

I’m particularly excited for build system documentation.

For anyone out there - if you see a comment that you think is particularly instructive, consider making it a doc or contact myself or one our mods and we’ll see if we can work it in.

And again, if you see something you think is inaccurate, out of date, or could be better, please be vocal about it and let’s get it updated so we can have clear documentation.

Here’s two tags that I would like to see filled out for the docs (and I’ll be adding to as well):

  • std… documentation about the standard library
  • build… documentation about the build system
8 Likes
4

Or even better: make the edit yourself! Docs topics are in Wiki mode by default so you can edit them by clicking the Edit button at the lower right below the topic content. Don’t be afraid to drive the change; no contribution is too small!

1 Like
5

What is helpful in the Python documentation is that it is explicilty indicated in which version a particular feature was introduced, as well as being able to look at older version of the documentation.

Although it is probably not feasable here to have multiple, version related versions of the documentation, I think it will be helpful to have some guidelines for the documentation to include “version introduced” information, as well as how to mark outdated documentation e.g. with version number range.

Apart from helping to find “new stuff” and not have to re-read all documentation posts, that could help with upgrading older zig sources. (And it gives the zigstorians a playground to document how things were done in the old days).

5 Likes
6

Adding a Zig version is a great idea. We should definitely start doing this imo.

7

I added the tags zig-0-11 and zig-0-12 to aid in this. It won’t enable a fully versioned docs system but can help when searching and filtering for something that applies only to a specific Zig version. Thanks for the great idea!

5 Likes
8

This is beautiful!!!

2 Likes