Documentation team: organizing an initial review of docs

[root-hal9000]

Hello, pinging everyone who is a member of @TriliumNext/documentation about getting started on an initial review and cleanup of the current material that will be the basis of user documentation and help. This comes from the original GitHub wiki by Zadam, but converted into regular static markdown pages to potentially be imported into a Trilium instance that will host the docs

We have been discussing some of this over on the Matrix channel/room, but I am not sure whether everyone in this team is there, and I wanted to make sure we have everyone's attention and input here.

So, in the docs repository, I just opened and organized a new project for getting through this review. I came up with a procedure for doing the review, as well as a set of standards for documentation. This was just the ideas I had in mind, with some input from folks in the Matrix channel. So I wanted to open it up for discussion here, and get everyone's input into these standards before we embark into this initial review - keeping in mind that we want to use these standards going forward as we create new documentation for updates and new features.

I am pasting the text I added to the project readme/description below. Please let me know what you think, if you have any ideas, etc. I bolded the parts I wasn't sure about, if anyone wants to chime in there too. Some of these are in screenshots - we might just need to have one person be assigned to screenshots to maintain consistency, but in principle, we should have standards so it's not dependent on a single member.

Also, if you are a member of the team, let us know if you are also in the Matrix chat room and what your username is there. I only know of 3 other people there who are also in the github team, so I am not sure how many people are aware of the discussion.

Ok, here is the whole project description, part of which of course will become the documented standards for creating future documentation:

---

This is an initial review to make sure there are no issues with the current documentation. We will divide it into sections and assign each section to a documentation team member who will review it. We will add a second step where another team member peer-reviews any changes and double checks the work.

Proposed procedure

We will have a branch called initial-review. Someone working on a section assigned to them via an issue should pull a new branch off the initial-review branch. Once they are done, they can create a pull request into the initial-review branch and request someone to review it. The peer reviewer then makes any necessary changes and merges the pull request. At that point, the issue can be closed.
When all issues are closed and everything is merged into initial-review, we can merge that back into main.

Review Standards

Approach your review with the eyes of a fresh new user trying to do something. Actually try to do the thing describe in the documentation, and check for the following:

• Without any previous knowledge about Trilium, can I accomplish what's explained in the documentation by strictly following only what's written in it?
• Is the language clear and unambiguous?
• Any language issues/misspellings or deviation from terminology used elsewhere in docs?
• Are more screenshots needed?
• Is the division of the document well structured using headings?
• Are step by step instructions marked with numbered lists?

Review Standards: Screenshots

• Do existing screenshots reflect current version? If not, create new ones.
• Use arrows/markers if needed to point out relevant elements, where to click, etc
  • let's use the color #fc3811 as a standard for uniformity
  • If indicating multiple clicks within a single screenshot, add numbers to arrows
• Currently, we have inconsistent theming in screenshots (some light, some dark). Let's make sure we are all using the same theme for consistency. I propose the Steel Blue theme, since it will differentiate itself enough from black or white background that might be used in a wiki
• GIFS: The current docs use GIFs in some sections. It seems many of these can be substituted by static images which can provide better accessibility.
  • If a GIF only shows clicks within a same page, substitute for a single static screenshot with numbered arrows
  • If a GIF shows navigation to another page, substitute for multiple static images representing each step where the action navigates to another page. If multiple clicks within a page, use numbered arrows as suggested above.
• Sizing:
  • Consistent Zoom factor of 1 in settings, or 100% in browser (do we need to agree on just using only desktop or only web in screenshots?)
  • for consistency screenshots should always show the full width of the user interface (Note: need to decide on a consistent zoom level)
  • The height of a screenshot can vary depending on what it needs to show, but by default, should always start at the top of the user interface (tabs, logo, note title are all visible)

I am currently working on rebuilding the TOC into the readme file. Once that's complete, I will create the new initial-review branch and we can create issues for individual sections which team members can volunteer to review.

[CrO2Cl2]

is there even any difference between the Desktop app and the browser app? ( for the screenshots )

[root-hal9000]

I typically just use my desktop app, but I just went looking at the browser version of my instance. I don't see much different - but maybe using the web version might be better for consistency, since I assume the desktop version might have some of its look affected by someone's OS settings?

Also, come to think of it, in terms of the look, I mentioned theme, but it might be better to just have a standard set of options for all the appearance settings for consistency. Things like people's screen resolution would affect consistency, but settings like the one below could help with that:

[meichthys]

There is also a setting specific to desktop apps that allows you to show the menu bar at the top or to just hide it. Other than that, the desktop app is just a browser embedded using Electron anyway.

[root-hal9000]

There is also a setting specific to desktop apps that allows you to show the menu bar at the top or to just hide it. Other than that, the desktop app is just a browser embedded using Electron anyway.

true, so if anything then, the look is more likely to be consistent in the the desktop app since there's no chance of someone's browser extensions making something different by accident, even if that's a tiny possibility

[CobriMediaJulien]

the look is consistent indeed. i work with my dev env and in my "trilium_work" instances. both is the pretty the same and the same skripts tho. Small difference is available hot keys.

[Alumniminium]

I'm not on matrix (and will never be) and had no idea about any ongoing discussions.

I've ported the entire wiki with @maphew and added a special token inside the markdown files to indicate things we will have to double-check.

This is an initial review to make sure there are no issues with the current documentation. We will divide it into sections and assign each section to a documentation team member who will review it. We will add a second step where another team member peer-reviews any changes and double checks the work.

A friend of mine is currently moving from obsidian to trilium and I'm using him to take notes about parts of the documentation that have to be updated / fixed / explained more verbose / with more examples.

No Idea how a TOC works in trilium / github wikis, so I didn't touch that part. I'll open a new issue however because nodbody has yet picked up the %%{WARNING}%%, I've created #87 to track that.

Also did we really need 85 issues for each wikipage instead of just one with a list... I find it pretty disturbing how this project already moves way too deeply into standards and management (process) overhead instead of getting work done. I'm always vary of people who try to implement standards and processes. More so of those who don't commit code.

[meichthys]

big bold font telling me i have to follow certain instructions,

That was my bad. I tested a few issue imports but tried to add a heading to the issue body without testing again. 🤦‍♂️

@root-hal9000 Did you want us to wait until the table of contents was finished before we started reviewing these individual pages?

[root-hal9000]

I was thinking it was better because it would mean less potential conflicts especially since I am renaming files, but you know what, I am doing a find and replace for those all across, so it doesn't matter. I should be able to get back on it shortly here and have it in the next couple of hours. I will open a initial review branch

[root-hal9000]

Regarding the GIFs... I am open to either thing. Personally, I am ok with short GIFs, the only thing I think makes it less accessible is when there are GIFs that show too many step and do so quickly , which can make it hard to follow since can't pause to see something clearly. But I don't think we have those? I guess reviewers can make judgement calls on that.

What about the screenshots? Do we think it's worth it making them all more standard, or not worth the hassle for now (could be done separately with more time). If we're doing them now, are the general guidelines ok?

Also, should we do them on some sort of clean install just showing demo content, or does it not matter?

[meichthys]

I agree with the trouble of long gifs. Short ones are fine, but I think the guidelines you created are good. IMO we might as well standardize while we have interest in it. I do think any screenshots should be taken using the demo content that comes preloaded with the releases.

[root-hal9000]

I am fine with short ones too. I am doing the TOC right now and will have it merged and review branch created from that soon
Another trouble with doing the arrows on screenshots thing I put out there - If we're going for a consistent look, and want to be picky about that, just choosing a color is not quite enough. For instance, I am using flameshot for screenshots - my arrows might look different from others unless we were all using the same software and exact settings.
One not so ideal solution is to just set aside the screenshots as a different project for a single person.
Or not be too picky :)

[root-hal9000]

Just another question regarding uniformity/standards. I just noticed that for headings, the original files use a horizontal line in the markdown, rather than a heading (which also renders a horizontal line). See screenshot where I changed the first heading into a a markdown heading. Does it matter? Does it render differently in any way in other circumstances?

[meichthys]

It seems like sticking to straight Markdown would be the most obvious choice. Unless there's a specific reason not to, I would probably opt to use the markdown heading and remove the horizontal lines.

[shutaozhenzhen]

horizontal line is a definition of markdown heading.

but I think ## is just better

[root-hal9000]

Should we script a replacement, or just too clunky and error prone for something people can just replace as they go?

[Alumniminium]

As we go is fine I think. we have TriliumNext/Docs#89

[maphew]

I'll be offline for the rest of July, so don't take lack of participation as lack of interest. ;- ) After that I'll engage in the docs project more energetically.

[root-hal9000]

Enjoy your offline time!

[Alumniminium]

I just wanted to take a moment apologizing for not doing any work on the documentation recently. I've been completely drowning in work from my job and usually just go to bed every evening doing absolutely nothing.

I have next week off, so I'll try to do a good chunk of work before I have to return to Mordor.

And I want to leave a big thanks to @root-hal9000 and @meichthys for keeping things moving along in the meantime. Thank you.

[root-hal9000]

all good, we all have our own crazy schedules and have to jump in and out. Thanks for your work!

[root-hal9000]

Hey everyone, I know we meant to only merge this at the end of the full review - but I was thinking it might be good to make at least one merge into main while still working on it? I was working on issue #191 on the Notes repo yesterday, and in testing the links, I was realizing how many things linked in the Notes repo's readme links to stuff in docs that has been cleaned up since the last merge. Since the dev team is readying that pre-release, maybe we should keep the main branch here more up to date, since it will be taking a little while to finish the whole review?
Thoughts?

[meichthys]

That sounds like a reasonable idea to me. We don't want to hold things up on the notes side.

[root-hal9000]

Sounds good. I will review the open PR, after merging that to initial-review I will merge into main while keeping the current initial-review going