How should I report outdated docs or suggest edits to the wiki?
I've been reading the docs after joining the site (hi!) and noticed a few places that were either outdated or unclear. Should I ignore them, given the disclaimer on the Instructions doc that says docs may not be current? Or is it better to report them?
Here's a list of what I noticed for context:
-
Docs, outdated: User settings: Marking new comments - this is now the default for logged in users and has been replaced by the "Collapse old comments when I return to a topic" setting.
-
Docs, minor typo: Commenting on Tildes: "Noise" label - "with no and Offtopic labels" seems to be missing a word between "no" and "and".
-
Docs, minor confusion: Navigating Tildes: Comment highlights - the meaning of "Linked comment" wasn't immediately clear to me.
-
Wiki, outdated: ~tildes wiki: Introduction: Settings - mentions the "mark new comments" settings
I recommend setting up [..] and toggle marking new comments to highlight new comments in a thread.
Some guidance on what to do with discoveries like these will be helpful for those who read docs :)
I'm not really asking them to be updated here and now, but that's a fine outcome of this post too.
I revised those docs about 6 months ago, but I haven't looked at them since. Maybe I should.
However, lots of people have edit access to the wiki, so posting here is probably the best thing to do, so everyone sees it.
Gotcha. I was a bit worried that (hypothetically) posting every minor typo might be noisy. I suppose we can apply a common tag to such posts if that becomes actually noisy and let people filter them out.
Well, yes, that would be. You need to use your common sense.
But, easier than that, you can use your newfound edit access to the wiki! No posts required. :)
That's not how it works.
We non-Deimos people don't have access to edit the official docs. We do have access to edit those wiki-based draft versions of the docs that @silfilim linked to. We can - and should - edit those wiki draft pages, and then Deimos will copy them to the official docs.
Thanks for the affirmation and a comprehensive answer. One pending confirmation on the GitLab part ;)
Thanks very much for the reports! The docs definitely need some updating. I'll go through today and make some of the changes you mentioned, but I've also given you wiki-editing permissions, so if there's anything else that you notice, please feel free to just edit the pages on the ~tildes.official wiki (when viewing a page, there's a blue button to edit in the page's sidebar). I'll review any edits and copy them over to https://docs.tildes.net sometime soon.
Oh wow, so much power on day two. Thanks!
@hungariantoast linked to the tildes-static-sites repo as a way to suggest edits, and @Algernon_Asimov corrected that we should edit the ~tildes.official wiki instead.
The repo's readme says contributions are welcomed though, while directing people to the wiki as a simpler method.
Does this part of the readme no longer apply? or is it still fine to make pull requests to the repo?
Hmm, I found this other repo: https://gitlab.com/tildes/tildes-wiki/-/tree/master/tildes.official - which is read-only.
Whoops sorry, was just looking back at this thread and realized I never replied to this.
Pull requests to the tildes-static-sites repo are fine (and could be the only option if someone doesn't have a Tildes account), but I'd generally prefer edits be made through the site's wiki system. It's easier to only need to merge things in one direction and tracks the history of who made which edits more properly.
The other tildes-wiki repo is actually what the site uses internally for wiki edits. Whenever someone edits a page, in the background it updates a markdown file and makes a commit to that repo (and pushes it up to GitLab).