JacquesCarette
Wiki: Discussion-Style Pages
Something I've noticed is that a fair number of wiki pages are what I'd call 'discussion pages'. Instead of laying out an 'outside-in' overview of a particular corner of Drasil so that anyone can get a good sense of that corner, they give an 'inside-out' discussion of a current problem with that particular corner. I see two problems with this style of page:
- They tend to be difficult to understand for anyone who wasn't in the room during the original discussion
- They tend to quickly go out-of-date. This is because they exist to document problems with the current system, and as soon as the problems are documented they are usually fixed.
Some examples of these pages:
- Attributes and Chunks
- Chunk Observations
- Attributes and Chunks, Meeting June 7th, 2023
- Investigation of Abbreviation Functions
I'm a little confused why these are wiki pages and not simply comments on the issues, PRs, and discussions that they relate to. They're incongruous with the rest of the wiki. I'd like to discuss some options we could take improve clarity surrounding them.
- Could we convert them into more traditional 'outside-in' wiki pages, at the risk of losing the discussion?
- Could we move the discussions back into the issues, PRs, and discussions they relate to?
- If we want to keep their contents as wiki pages, can we find a way to explicitly mark them as discussions? E.g. changing their location in the sidebar, adding a tag, etc. This would make their purpose clearer to both newcomers and maintainers.
The answers might need to come on a case-by-case basis. It likely depends on whether the issue is still ongoing and whether the discussion has information worth showing to more users of Drasil.
Obviously some of this is my own opinion, and these pages exist for a reason. I just find their placement a little confusing, and it's worth asking if we can rearrange things to improve that.
Contributes to #4401
@B-rando1 those are great observations. You are absolutely correct about how some of those pages came into existence. We had a discussion that we wanted to capture, so we put it in the wiki.
You are right that these "inside" discussions aren't very useful to new people, but moving the discussion into the PRs, issue tracker and discussion forum isn't ideal either. @JacquesCarette and I recently had a discussion with @balacij about how difficult it is to search through GitHub for relevant information. If you can remember some key phrases from a relevant discussion, you still might never be able to find that discussion. The search features aren't great. Putting the content in the wiki makes it easier to find. I just verified that there is a search feature for the wiki. :smile:
The problem with writing "outside" documents is the time that they take. They are obviously more useful, but is there enough return on investment for putting time into them?
Maybe we should have a set of curated links in the wiki. We could move the discussion to where it belongs (in an issue, PR, discussion post), but then have a description of the topic and a link in the Wiki?
We can discuss this in today's meeting.
As we discussed in the meeting: these should be moved into a "Working Notes" (or similar) parts of the wiki, not hooked directly to the sidebar, except via a single "Working Notes" page.
I've been classifying the wiki pages during my current pass, so I can move all the "Working Notes" pages once I finish.