Improving the docs
Is there anything that can be done to improve the docs? I am starting this discussion in order to brainstorm and discuss any ideas for improvements.
Currently the docs can be found on this discussion category, and on the github:
- https://github.com/debiki/talkyard/tree/main/docs
- The Talkyard Community
- https://github.com/debiki/talkyard-prod-one/tree/main/docs (for self-hosting)
Lots of projects have a separate and dedicated website for the docs, like docs.talkyard.io. I am not sure if this would be a good idea for Ty too. If yes, then there are several documentation frameworks that can be considered, for example:
They usually follow the documentation-as-code approach, where the code of the docs (Markdown or AsciiDoc files) is stored in a GitHub/GitLab repository, where the pull-request (or merge-request) workflow can be used to suggest and apply changes to the docs. Once some changes are approved and applied, then CI/CD tools are used to automatically regenerate and update the docs website (maybe using GitHub/GitLab Pages).
Another thing to be discussed is the structure of the docs. Usually the docs are organized in different categories, intended for different audiences or different use cases. For applications like Ty, I think that at least three categories are needed:
- Docs for sysadmins, that explain how to install the application, configure, setup, update, maintain it, etc.
- User docs, that show how to use the application, including the docs for administrators, moderators, etc.
- Developer docs, which explain the internals of the application, its architecture, design, structure, APIs, etc. These docs may be potentially useful for new developers, to help them get started quickly.
We would appreciate some feedback and discussions from the community. If we manage to define a clear documentation project, we may also apply for sponsorship from Google Season of Docs.
KajMagnus @KajMagnus2023-01-31 07:10:23.306Z2023-01-31 07:31:47.394ZHi Dashamir, Good idea (to improve the docs), this is needed I think. (There's some installation & maintenance docs as well at: https://github.com/debiki/talkyard-prod-one/tree/main/docs; I edited the orig post and inserted a link.)
at least three categories are needed [...] sysadmins [...] user docs [...] developer docs
Yes, some thoughts about these categories:
-
End user docs: (including for Talkyard admins and moderators, but not Linux system admins)
- Where's the best place to show end user docs? I think it's in Talkyard itself: Whenever someone looks at a dialog or UI wiget wonders "what's that?" or "how does this work?", then s/he can from inside Talkyard, click a
[?]button to open a help dialog describing that part of Talkyard. - But it's also nice with a static website with end user docs, so one can browse and explore everything, outside of Talkyard.
- The above leads us to using MDX for end-user docs. (MDX = Markdown with React.js support, https://mdxjs.com). MDX help pages can be loaded by Talkyard's web app (it uses React.js), and shown in help boxes. And MDX works with static website generators. MkDocs doesn't seem to support MDX, however, Docusaurus does (which I like).
- Where's the best place to show end user docs? I think it's in Talkyard itself: Whenever someone looks at a dialog or UI wiget wonders "what's that?" or "how does this work?", then s/he can from inside Talkyard, click a
-
Sysadmin docs: (for self-hosting Ty)
- It's good if these are available offline, for a sysadmin who installs Ty on an air-gapped network. And withouth having to start any static docs site oneself. — So I think they should be available in the
talkyard-prod-oneGit repo (which they are, already) or in a docs Git submodule that gets downloaded automatically bytalkyard-prod-one. - It'd be nice to include the sysadmin docs in the above-mentioned static website too. So these docs need to be in Markdown or MDX format as well. Either there can be just one docs Git repository with all docs (excl dev docs, see below). Or if the sysadmin docs are kept in the
talkyard-prod-oneGit repo, then that repo could be added as a Git submodule to the main docs repo. That might be simpler; then, one would always get the sysadmin docs for the correct version and installation method of Talkyard. (I'm guessing this sounds a bit confusing.)
- It's good if these are available offline, for a sysadmin who installs Ty on an air-gapped network. And withouth having to start any static docs site oneself. — So I think they should be available in the
-
Developer docs: These are off-topic and confusing for 99.9% of everyone :- ) and I think it's better to not include them in the static docs website. (As a bad example (or so I
thinkthought), look at the Zulip docs — they bundle dev docs and "real" docs together, and if one searches for something, e.g. "installation": https://zulip.readthedocs.io/en/latest/search.html?q=installation, the top search hit is "Development environment installation", off-topic to almost everyone. [edit] Oh I was wrong, they actually do have a separate docs website for end-user docs: https://zulip.com/help/. [/edit])The dev docs are those you found at
github.com/debiki/talkyard/tree/main/docs. I think people will read the dev docs via code editors like VSCode, in parallel with editing the source code, and sometimes browsing ... via GitHub? Or maybe a dedicateddevdocs.talkyard....subdomain? — Anyway I think the dev docs are out of scope of a Google Season of Docs project.
The docs here at forum.talkyard.io?
What about the docs here in this category: https://forum.talkyard.io/latest/docs — I think that's not the right place for the docs, because it's hard to download them to one's own laptop. (To do so, one would need to crawl the Ty .io forum with a web spider? That's very not-user-friendly.)
Instead, the docs should be in a Git repo, so
git cloneis all that needed. — It'd be nice if the docs in such a Git repo, was still searchable from the Talkyard .io forum. There are some plans to make it possible to index an external documentation website, in Talkyard, and then, when searching for help here atforum.talkyard.io, you'll get linked to that external docs website (instead of Talkyard discussion pages). (And if people have questions/comments about the docs, maybe there could be Talkyard comments below each docs page.)I'll write more later
... about some end user docs I think are missing and other things ...
Dashamir Hoxha @dashohoxha-
About developer docs: If Talkyard can be extended with plugins or modules, you certainly need to describe how to build them. If Talkyard can be accessed from an API, you certainly need to describe the details of this API. It is also useful to document the core of the application (for example the DB schema), so that it can be (potentially) extended and improved by other people, besides the main developer. But I completely agree that dev-docs should be left outside the scope of the GSoD project, at least for this year.
-
The docs at forum.talkyard.io? There is nothing wrong with them, except that they cannot be structured. In my opinion, a discussion forum may be a complement, but not a replacement for structured docs.
-
Talkyard is self-documenting, with wizards etc. This is very nice and useful, but still not a replacement for real documentation (in my opinion). If you click a
[?]button, you can also open a section from the docs on another tab, instead of opening a help dialog. This seems cleaner to me. So, I am not sure if MDX is really necessary. -
Keeping docs in several GitHub repos: Antora can aggregate doc files from different Git repositories, in order to generate the doc website. So, there is no need to use Git submodules or tricks like this. Antora can also have "documentation components", for example one component for the end-users, one for sysadmins, etc. But it is also ok to have separate websites for end-user docs, sysadmin docs, etc. (like Zulip).
-
Adding Talkyard comments below each doc page: This would be nice. I modified recently the template of my TechBlog website to include Talkyard comments at the end of each page: https://dashohoxha.fs.al/docs/server-setup.html#_install_docker_compose This site is built with Antora (with some small modifications in the default template).
KajMagnus @KajMagnus2023-02-01 06:42:01.466Z2023-02-01 07:42:40.805ZThanks for the reply, some clarifications:
Developer docs. We meant different things. With dev docs, I had in mind docs for developers who want to edit Ty's source code and develop Talkyard itself. (Which is off-topic to almost everyone.)
Whilst you had in mind API docs for developers who write their own external software and interact with Ty via API requests. And for others who use e.g. Zapier (or other no/low-code tools) to connect their IT systems to Talkyard. (Which is somewhat common.)
I'd place these docs in a technical section of the end user docs, maybe with a title like "API Documentation". And yes definitely API endpoints should be documented.
docs at forum.talkyard.io [ ...] cannot be structured
Hmm what do you mean with "structured" here? There are categories and tags in Ty (not too different from most static site generators?).
If you click a
[?]button, you can also open a section from the docs on another tab, instead of opening a help dialog.When the docs about something fits in a dialog box, then personally I'd prefer to see the docs in a dialog. So I didn't need to switch between tabs. (On laptops, this would usually be the case.)
And such a dialog, would include a link to the docs over at the static site, so if one wanted to read the docs over there (maybe to see more details, or look at related / nearby things, in the menu tree), one clicks the link and then gets the docs in a new browser tab.
Keeping docs in several GitHub repos
I think there'd be one or two, not more. ... Hmm ..., long term, I suspect it's good to keep also the sysadmin docs (about installation and maintenance) in the same repository (then there's just one repo).
This site is built with Antora
It looks nice I think. Hmm, ... and, Antora has the annoying (I think) menu-position-lost problem: If clicking an item in the left menu, then, the whole page reloads, and one's scroll position, and which sub menus one had expanded or collapsed, is lost. And, if the menu is tall, then, to see the nearby menu items (e.g. to click & read about sth related), one needs to manually scroll down in the left menu again, and find one's current location. — I actually spent some time long ago, finding a static site gen that doesn't have this problem (most of them have this problem), and that's one reason I came to like Docusaurus.
Antora can also have "documentation components", for example one component for the end-users, one for sysadmins
Is that sort of different main "categories", you don't happen to have a link to docs about this? (Maybe something at: https://docs.antora.org/antora/latest/ but I didn't find)
- Dashamir Hoxha @dashohoxha
Developer docs. We meant different things. With dev docs, I had in mind docs for developers who want to edit Ty's source code and develop Talkyard itself. (Which is off-topic to almost everyone.)
We didn't mean entirely different things, because I also had in mind docs for developers who want to improve Talkyard itself (or fix any bugs, maintain it, etc.)
I'd place these docs in a technical section of the end user docs, maybe with a title like "API Documentation". And yes definitely API endpoints should be documented.
Probably you are right, but I would also get some opinion from any professional technical writer (I am not professional), or look at other projects, how they do it. You may be completely right about something, but it also matters what people expect, what they are used to.
Hmm what do you mean with "structured" here? There are categories and tags in Ty (not too different from most static site generators?).
I mean the tree-like index that you usually see on the left side of documentation sites (for example the docs of Zulip). You may try to imitate it with sub-categories, but it seems to me a bit awkward. Ty was not meant to be a documentation tool, is it?
When the docs about something fits in a dialog box, then personally I'd prefer to see the docs in a dialog.
Then you have to use different methods for cases when docs fit in a dialog box, and when they are too large for a dialog box. You have to make a decision which method to use on a case-by-case basis. If docs change and grow, you have to reassess the method for each case. But if this is what you like, it is fine.
Antora has the annoying (I think) menu-position-lost problem: If clicking an item in the left menu, then, the whole page reloads, and one's scroll position, and which sub menus one had expanded or collapsed, is lost.
If this observation is made based on my website, you should know that I have customized the default template of Antora to look and behave more like a blog.
Is that sort of different main "categories", you don't happen to have a link to docs about this? (Maybe something at: https://docs.antora.org/antora/latest/ but I didn't find)
The docs about this are not actually very clear: https://docs.antora.org/antora/latest/component-version/
But you can see from this screenshot (on the buttom-left) that Antora docs has 3 components, and each of them has different versions.
- KajMagnus @KajMagnus2023-02-08 13:47:38.328Z
I also had in mind docs for developers who want to improve Talkyard itself [...] get some opinion from any professional technical writer [...] look at other projects
Ok :- ) Yes I've had a look at e.g. Zulip and Discourse and Mattermost, and they all do things differently:
- Zulip: has docs at four places:
- https://zulip.com/help/ — end user admin, moderator docs
- https://zulip.com/api/ — API docs
- https://zulip.readthedocs.io/en/latest/production/install.html — self hosting docs
- https://zulip.readthedocs.io/en/latest/contributing/contributing.html — for contributors
- RocketChat has:
- All docs in one place: https://docs.rocket.chat (end user, self hosting, API) ...
- ... except for developer docs: https://developer.rocket.chat
- Matrix:
- Everything (incl developer docs) at the main website: https://matrix.org/docs/
- Discourse:
- End user docs at www & their blog: https://blog.discourse.org & https://www.discourse.org (e.g. /plugins)
- API docs: https://docs.discourse.org
- Self hosting & contribution docs at GitHub
- Mattermost has three separate sites:
- https://docs.mattermost.com — end user & admin & installation docs.
- https://api.mattermost.com — API docs.
- https://developers.mattermost.com — dev & contribution docs, webhooks docs, etc.
- Mastodon has everything in one website:
- https://docs.joinmastodon.org — end user, admin & mods, installation, API, contribution docs.
- Ghost seems to have everything in one website — for installing & contributing. Maybe a blog doesn't need any end user docs: (just reading & commenting)
I start thinking that what a technical writer would say, would be his/her personal opinions. And depending on whom you'd ask, you can get any answer :- )
Hmm what do you mean with "structured" here
the tree-like index that you usually see on the left side of documentation sites
Ok. Yes that's nice to have. And yes the static site generators do that better, definitely, I think.
Then you have to use different methods for cases when docs fit in a dialog box, and when they are too large for a dialog box
Actually, not so much (I think/hope) — with docs in MDX, I think it'll work fine to use as-is both from inside Talkyard-the-app, and when accessed from the static-docs-site too. Maybe you could say it's like deep linking to the right parts of the documentation, and having it appear in a dialog in the Ty app. Maybe hard to explain in text what I have in mind.
If this observation is made based on my website
(Partly, and also Antora's main website, although it at least remembers & scrolls to one's current place in the left menu.)
documentation components [ ...] The docs about this are not actually very clear: https://docs.antora.org/antora/latest/component-version/
Aha then I understand. (Supported by Docusaurus too fwiw, but maybe not so many others.)
- Dashamir Hoxha @dashohoxha
Some of the apps that you have looked at are not good documentation examples. For instance I have installed mastodon recently and I have to say that the navigation of its docs is terrible. The content of the docs is also outdated (at least 2 months ago, that I was looking at it).
If you like Docusaurus that's fine. As long as the content of the docs is in markdown format, it should be easy to move to another framework, if needed (if you later change your mind about Docusaurus).
The most important thing right now is to create a project proposal page, following these instructions:
https://developers.google.com/season-of-docs/docs/org-proposal-template
Right now it doesn't have to be complete or perfect, because you can refine it later.
It is also important (in my opinion) to list this project page here:
https://github.com/google/season-of-docs/blob/main/2023-participants/interested-organizations.md- KajMagnus @KajMagnus2023-02-26 09:31:40.642Z
Ok :- ) Yes I'm going to try to submit a proposal in about a week. I'll notify you first if you want to give feedback first.
- PPierre Godfroid @Pierre_G
About good self-hosted documentation app, I would recommend Outline.
I recently installed it on my own server (with the use of the Yunohost app, a kind of docker).
It is modern and pro. https://www.getoutline.com- KajMagnus @KajMagnus2023-03-29 17:28:55.053Z
Ok yes I've seen Outline, I think I like it (and even been wondering about some integration with it some day).
Doesn't look, though, as if docs hosted in Outline can be
git clonedownloaded by anyone and copied elsewhere, or contributed to / looking-at-changes via Git. Those things are, I think, important for an open-source project.
- Zulip: has docs at four places:
-
-
- Progresswith doing this idea