• voy4g3r2
• WorkingReOrgWIki

Framework to evaluate content re-arrangement

Table of Content

Objective

To evaluate and address anomalies, organization and missing links within the Wiki system. The Wiki system is a valuable source of information, that over the years, has required some updates and refinement to the content.

The analysis and approach here is only focused on data/information organization and not underlying technology components of the sytsem.

Assumptions

1. Categories, currently available, are used as grouping mechanisms and are subject to change
2. Category hierarchy will be limited to two levels of depth
3. Official documentation source, from docs.freebsd.org git repository, superseded wiki

4. Wiki pages that are classified (as per HelpOnMacros) can be addressed:

   1. Abandoned Pages (Macro: AbandonedPages)

   2. Wanted Pages (Macro: WantedPages)

   3. Orphaned Pages (Macro: OrphanedPages)

5. Efforts by the team, and documented at: Next Generation Wiki Ideas should be considered.

Anomalies

• - User Accounts are outdated - Wiki content is out of date
  • - ACTION ITEM: Need to be able to evaluate what conditions make something out of date.

  - Pages that are stale get a label of CategoryStale

Goals

• - To get the wiki page in a state that is not considered "stale"
  • - Stale is not yet defined but it should at least have the items in Common Errors section
  - Reinforce the need to be descriptive in changes presented to the Wiki Page

Criteria for resolution

- How do we determine something is stale?

• - Date of last update? - Mention of Dates in it?

  - There is a designation of CategoryStale

• - What is considered relevant and does it align to below categories? - Who are the parties involved, in the sense of "ownership"
  • - Based on a RACI (Responsible, Accountable, Contributor, Informed) Matrix
  - How do we document the "process" and what are triggers for progression?

Current State

1. Category: Historical

1. This is just a list of "historical pages"
2. The definition just seems to be based on dates
3. SUGGESTION: Move this all to an Archival area
   1. Folders Identified as DevSummit/ stay together

   2. Folders Identified as SummerOfCode"year"/ stay together

   3. All other entries in main archival area

2. Category: Community

1. Main Page calls this FreeBSD Community
2. SUGGESTION: Remove FreeBSD just call Community
   1. Based on, recommendation in wiki, everything is FreeBSD
3. Sub Pages

   1. IRC Channels

      1. BACKGROUND: List of IRC servers that the community uses
      2. SUGGESTION: Leave it alone, nothing jumps out as change

   2. Discord

      1. BACKGROUND: This page just has links to Discord Server and Client
      2. SUGGESTION: Consolidate these two links into one page, remove sub pages

   3. Matrix

      1. BACKGROUND: Discusses Matrix Servers and is considered experimental as of 2023
      2. SUGGESTION: Determine how we would update this page

   4. Forums

      1. BACKGROUND: Link to the forums
      2. SUGGESTION: Leave alone, no action

   5. Twitter #freebsd

      1. BACKGROUND: Link to hashtag and Twitter
      2. SUGGESTION: Update to the new name of X

   6. Mastodon- bsd.cafe

      1. BACKGROUND: Has one mastodon server (bsd.cafe)
      2. SUGGESTION: Leave it alone, looks good

3. Category: Popular

1. About

   1. BACKGROUND: Appears to be a general about and suggestions area
   2. QUESTION: How did this category naming convention come about?
   3. QUESTION: What was the determining factor to populate entries within it?
   4. SUGGESTION: More in-depth analysis required to find a "new home", if required

2. Wiki Guidelines

   1. BACKGROUND: Guide to how to interact with the Wiki Guidelines
   2. SUGGESTION:
      1. Consolidate all Wiki Guidelines material into one location.
      2. Align different categories and sub-pages into logical groups

3. git

   1. BACKGROUND: Information about git source control tool

   2. SUGGESTION: Maybe just update this to point the handbook: Appendix A. Obtaining FreeBSD

4. Git Tips

   1. BACKGROUND: Best practices and tips on git source control tool

   2. SUGGESTION: Consolidate with the Git to reduce "spread" and build on that suggestion

4. Category: Contribution

1. Category: Contribution Ideas

   1. BACKGROUND: A list of cool projects and ideas, spanning multiple years
   2. SUGGESTION: Do a divide and conquer, how to reorganize this whole page, initial pass.. there is a lot of good stuff in here. Some of it may be outdated

2. Category: Google Summer of Code

   1. BACKGROUND: Official FreeBSD page link to history of the Google Summer of Code initiatives, from 2005 - 2024
   2. SUGGESTION: Find all links, throughout the Wiki, and reference this page as the source (this is a mixed bag) and requires a deep-dive

3. Category: Google Season Of Docs

   1. BACKGROUND: Documentation Project page, associated with Google Season of Docs, not sure what this even is. The page looks to be a consolidated "re-hash" of the documentation documentation for Handbook. This was a project the team did one and never picked up after that. May be worth just archiving
   2. SUGGESTION: Confirmation of what this page's purpose is and determine if required to be "folded" into another page. Other possible option is just archive the whole page.

4. Category: Becoming A Committer

   1. BACKGROUND: A good complement to the Developer's Handbook and gives additional context not available in the handbook
   2. SUGGESTION: Consolidate this into one set of pages, no matter if new or old, and bring the Developer Handbook wording higher up in the page (currently at bottom)

5. Category: New Contributor

   1. BACKGROUND: A supplement, similar to the above one, just focused on a new people
   2. SUGGESTION: Fold this information into one page and delineation between the two types, with the handbook also

6. Category: Maintain a FreeBSD Port

   1. BACKGROUND: Documentation on how to maintain a port
   2. SUGGESTION: I think this should be rolled into the contributor area.. a port, doc, other stuff, is all under umbrella of contributor

7. Category: Update a FreeBSD Port

   1. BACKGROUND: Documentation on how to update a port
   2. SUGGESTION: I think this should be rolled into the contributor area.. a port, doc, other stuff, is all under umbrella of contributor

Classification of Sections

• - Capturing data dump, as these points are great and should be at least capture.

  - bugs site => devops tool - collaborate on bugs => devops tool - mailing lists => devops tool - use bugs to track projects => devops tool - browse the repository => devops tool - release notes on main web site => devops tool - discuss project activities in discord/IRC => devops tool - different UI between projects => devops tool - limited guidelines for how major projects share progress => devops tool - wiki project tracking and milestones => devops tool - phabricator (off support since 2021) for code review => devops tool - release notes not tightly integrated with commits => devops tool

Metadata Analysis of the Wiki layout

Analysis perform by a team member, on discord, named Gaelan. Awesome analysis and just placing the link for collection. Analysis of Wiki

Future Layout Goals

1. Knowledge Base Category Templates

1. Style Guideline Templates Guidance b. Draft Area c. Test Area d. Production Area e. Archival Area

   1. Items we could not find a home for
   2. Historical in nature

- Articles CategoryCategory

• - Style Guideline - HelpOnTemplates - Draft Area - Test Area - Production Area - Archival Area

  • - Items we could not find a home for - Historical in nature

  - Blog Post CategoryCategory

  • - Style Guideline - HelpOnTemplates - Draft Area - Test Area - Production Area

  - Man Pages (test) CategoryCategory

  • - Style Guideline - HelpOnTemplates - Draft Area - Test Area - Production Area

  - Handbook CategoryCategory

  • - Style Guideline - HelpOnTemplates - Draft Area - Test Area - Production Area