Hi all -
After a looooooooong time away and not doing very much, I finally got my act together and have put my documentation proof-of-concept onto Github.
This is particularly aimed at the layout of the ZIG standard library documentation which is (IMO) a bit cluttered and “busy” (like Times Square in rush hour… ).
I’ve put the HTML, CSS and javascript under the Unlicense, and the text content (including any Zig code in it) under the MIT license as that is what Zig uses (IIRC).
I have also very strongly recommended that people not use the content as documentation as such - its primary purpose is to give a proof of concept for layout and how sections of documentation can relate to each other (in this case, using tabs).
I’ve also included a number of themes.
I think you’ll particularly like the police-style “PULL OVER, BUDDY!” theme…
Anyway… enjoy!
Comments and suggested improvements welcome.
I don’t plan on spending a lot of time on the repo now (and it may even only stay there for a limited time - a month or two - unless people really really like it. )
It’s not entirely clear what this tries to document, do you intend this to be a tutorial of programming with Zig in general, or is it intended to replace the official docs at https://ziglang.org/documentation with a better ToC?
Is the contents of the texts of any relevance at all? It seems a bit random and all over the place in writing style and how much depth it is going into, which is typical for AI generated stuff. That’s fine for placeholder stuff though, and IMHO much better than Lorem Ipsum.
To be honest, knowing that everything including the code and the text is AI generated is usually a big red flag for most people. Also, as AI generated code and text is not copyrightable, the MIT license is thus mostly useless.
No, it is definitely not aimed at replacing the official Zig docs.
As I mentioned, the aim is layout - not use as documentation, and I strongly advised against using it as documentation.
( You may have missed that part… )
It is aimed in particular at the layout and appearance of the Zig standard library documentation (which I find quite cluttered and difficult to get the “big picture” from.).
Take the Build module, for example. The current standard library docs show one small piece of it at a time, whereas if it were laid out similar to what I have in doc_poc, you could see (in the sidebar) all of the relevant sub-modules of Build at once and easily click to each of them.
The same goes for the other modules.
That’s what I mean by “seeing the big picture”.
I should stress very strongly that it is necessary to fork or download the repo and go into one of the three HTML pages using a web browser to get the full idea of the “what is possible” experience that I’m trying to give doc users.
I apologise if my aims were not made clear! I don’t mean for doc_poc to offend or have any negative effect on Zig - I was hoping for quite the opposite!
Is there anyone out there who can see the positives in the layout that doc_poc shows? Very keen to hear from you!
)