The title naming conventions are designed to standardize page titles across the Wiki, making it easier for readers to accurately locate content through the search bar.
Each page title should follow the format [Tag] {Title}. Here, Tag is a short, capitalized keyword enclosed in square brackets, indicating the page’s category or topic summary. To ensure clear categorization, use the Tags listed on this page whenever possible instead of creating custom ones (If you do need to use a custom tag, place it at the end of the tag list). Multiple tags are allowed, with the main tag placed before sub-tags, like [MainTag][SubTag] This Is A Title.
Titles should follow English title capitalization rules, and be as concise and precise as possible. Short phrases are preferred over full sentences. For pages under the [Device] tag, the title should be the name of the device.
We define the following Tags:
[Navigation]: Used for organizing tables of contents, indexes, and navigation pages to help users quickly locate content.[Device]: Introduces various devices, including their functions, parameters, and usage. The title should be the device name.[Tutorial]: Offers systematic how-to guides for learning skills or workflows step-by-step.[GUI]: Focuses on software-related topics, such as settings, panels, and user interface operations.[Macro]: Covers the creation and usage of macros.[Bluemap]: Covers the usage of blueprints.[Code]: Introduces the use of Code devices, including interface documentation.[Idioms]: Documents typical use cases, best practices, and conventional workflows to aid in understanding common approaches.[Sundries]: A flexible tag for miscellaneous content that doesn’t fit other categories. Topics should still remain relevant and concise.
Tags for Wiki contributors and internal development include:
[Diction]: Defines writing conventions, terminology usage, and stylistic guidelines.[Discussion]: Records drafting processes, design ideas, and community discussions. Sub-tags are recommended to clarify the topic, e.g., [Discussion][Device] Some Discussion About Perlin Noise.[Announcement]: Used for important Wiki-related announcements, such as current plans or official statements. Content should reflect community consensus.
1 Like
This is just a suggestion for now, and the specific implementation method still needs community discussion.
1 Like
Seeing as we already have multiple “convention” related posts (See: Writing conventions) in the Wiki category, I think this would be a good time to mention that the Wiki format allows editing existing contributions.
As someone that worked for big companies that utilized Confluence, the one thing we do not want is to fracture content in ways that cater to:
- Risk of repetition that leads to persistent stale content.
- Risk of convoluting information.
- Risk of convoluting the process of contributing.
- Treating the Wiki section as a disjoint messaging forum.
A Navigation index is alright, but search engine indexing could still prioritize topics themselves, and then we enter into the realm of, “This is outdated, let me make a new updated version”, or “This is not quite what I was after, let me make another topic about this” without a search. Also, the Navigation index needs to be updated for every contribution… and well… now we have another avenue of error.
TL;DR: Let the Wiki topics themselves act as the index, properly itemize content, and update the proper topics with the information. Let us keep the Wiki clean, concise, and easy to maintain.
1 Like
I completely agree with these flaws. The navigation of content should appear when the entire Wiki community is relatively complete, and then the content will be organized into an index page. A more appropriate way than indexing topics should be a menu page, but I haven’t found a better way so far. The reason is that I hope to organize topics in a systematic way. After all, our wiki should be a standardized document, not a simple collection of tutorials.
In addition, since our wiki is still in its infancy, I suggest using the navigation topic as a task list to show what has been completed and what has not been completed. I imagine that we should build the navigation index first, leaving the hyperlink blank to indicate that the current page is unfinished. Since the topic can be regarded as a shared document, editors can also mark the work they are doing on the entry, so as to avoid multiple people doing the same work at the same time.
In fact, it would be better to establish a git repository in terms of our work (almost all of the above problems can be solved), but so far I have not thought of a good way to connect the repository with the forum (maybe it’s possible to automatically map forum pages to a file page in the online repository? I’m not sure, it’s up to the developers).