13 votes

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:

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.

10 comments

  1. [4]
    Algernon_Asimov
    Link
    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,...

    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.

    6 votes
    1. suspended
      Link Parent
      I'll tag @cfabbro. Maybe, they'll know more about what to do.

      I'll tag @cfabbro. Maybe, they'll know more about what to do.

      4 votes
    2. [2]
      silfilim
      Link Parent
      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...

      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.

      1 vote
      1. Algernon_Asimov
        Link Parent
        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. :)

        I was a bit worried that (hypothetically) posting every minor typo might be noisy.

        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. :)

        2 votes
  2. [3]
    hungariantoast
    (edited )
    Link
    First, if you notice anything that does not look right, or you think it could read a bit better, then absolutely, please report it! (And you already have here, so thanks!) Anyways, the official...

    First, if you notice anything that does not look right, or you think it could read a bit better, then absolutely, please report it!

    (And you already have here, so thanks!)

    Anyways, the official Tildes documentation lives here:

    If you wanted to make some changes to that, you would have to open a pull request on GitLab.

    The pages you're linking to are part of the Tildes Wiki and are editable from the site itself. However, to edit those pages, you need to be granted a special permission.

    As for getting others to make changes and update things, just making a post like this is probably good enough to get those updates made. Users who already have permission to edit the wiki will notice and (probably) fix things soon.

    Otherwise, if you would like to ask for permission to edit the wiki yourself, or if you notice something particularly egregious in the wiki or site documentation that really needs to be updated, you can also just message Deimos, the site's admin, to make him aware.

    5 votes
    1. Algernon_Asimov
      (edited )
      Link Parent
      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 -...

      Anyways, the official Tildes documentation lives here:

      https://docs.tildes.net

      If you wanted to make some changes to that, you would have to open a pull request on GitLab.

      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.

      5 votes
    2. silfilim
      Link Parent
      Thanks for the affirmation and a comprehensive answer. One pending confirmation on the GitLab part ;)

      Thanks for the affirmation and a comprehensive answer. One pending confirmation on the GitLab part ;)

      2 votes
  3. [3]
    Deimos
    Link
    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...

    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.

    5 votes
    1. [2]
      silfilim
      Link Parent
      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...

      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.

      In general, contributions (edits or adding new pages) are welcome for the Docs site (files inside the content/pages/ directory).

      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.

      2 votes
      1. Deimos
        Link Parent
        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...

        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).

        3 votes