Trilium Next
Documentation team: organizing an initial review of docs #188
Replies: 7 comments 24 replies
-
|
is there even any difference between the Desktop app and the browser app? ( for the screenshots ) |
Beta Was this translation helpful? Give feedback.
-
|
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: |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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.
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 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. |
Beta Was this translation helpful? Give feedback.
-
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? |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
horizontal line is a definition of markdown heading. but I think ## is just better |
Beta Was this translation helpful? Give feedback.
-
|
Should we script a replacement, or just too clunky and error prone for something people can just replace as they go? |
Beta Was this translation helpful? Give feedback.
-
|
As we go is fine I think. we have TriliumNext/Docs#89 |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
Enjoy your offline time! |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
all good, we all have our own crazy schedules and have to jump in and out. Thanks for your work! |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
That sounds like a reasonable idea to me. We don't want to hold things up on the notes side. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
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:
Review Standards: Screenshots
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.
Beta Was this translation helpful? Give feedback.
All reactions