Wiki: Migrating and Integrating Design Documentation #73275
Labels
No Label
Meta
Good First Issue
Module
Animation & Rigging
Module
Core
Module
Development Management
Module
Eevee & Viewport
Module
Grease Pencil
Module
Modeling
Module
Nodes & Physics
Module
Pipeline, Assets & IO
Module
Platforms, Builds, Tests & Devices
Module
Python API
Module
Rendering & Cycles
Module
Sculpt, Paint & Texture
Module
User Interface
Module
VFX & Video
Priority
High
Priority
Low
Priority
Normal
Status
Archived
Status
Confirmed
Status
Duplicate
Status
Needs Information from Developers
Status
Needs Information from User
Status
Needs Triage
Status
Resolved
Type
Bug
Type
Design
Type
Known Issue
Type
Patch
Type
Report
Type
To Do
No Milestone
No project
No Assignees
5 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: blender/blender-manual#73275
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
This is the root design task for the work discussed here on DevTalk.
We have a number of module pages that use archived documents as active design references. Using archived documents as active references is messy, as it makes it hard to tell what is or isn't relevant in the old wiki. To fix this, we can:
This design task is going to explore the second option, using the UI Paradigms and Tab Guidelines documents linked to on the #user_interface project page as a starting point.
Structural Concerns
The categorizes and sub-categories in the wiki sidebar aren't based on a page/sub-page structure in the wiki itself. We have a lot of islands, with inconsistent bridges and signage, which means there isn't an easy home for design documentation.
Three options are:
/Design
section for design documents/Source/Design
sub-section for design documentsAdding a
/Reference/Design
sub-section for design documentsThe first option would be the easiest, but it'd continue the wiki's horizontal trend. The second option would put the documents in a reasonably predictable place that's already linked to in the sidebar, but it would create tree depth inconsistencies. The third option is superficially logical, but the root
/Reference
page is an island with unfocused content.I'm good with either the first or the second option, and I could be sold on the third. As long as the documents are grouped together in a consistent fashion, I can make it work.
Contextual Concerns
Design documents lose their validity gradually. There'll be documents we'll want to migrate that are 85% valid, but we don't have the time or resources to update them properly — which means we'll need a protocol for flagging and contextualizing them. If we don't, we'll end up exacerbating the issue we're trying to fix.
I'm in favor of prefacing these documents with a notice — using
{{Note | Note title | note content.}}
for now and making a more specific template later on — that describes the provenance of a migrated document.Here's the format I'm using in my drafts:
There are situations where we'll want a more verbose preface, but a brief one should work for most documents.
Copy Editing Concerns
This section is largely superficial, but it's here for the sake of thoroughness.
The old wiki pages contain a smattering of typos and typesetting errors. Most of them are superficial things, like using
->
instead of→
, and they don't really matter in the scheme of things. I can fix these issues to satisfy the voice in my head, or I can leave them alone for the sake of historical accuracy.Process Concerns
I'm used to doing pre-pub review, and it wouldn't be hard to create tasks here on phabricator with links to drafts on my wiki userpage. I'll follow the #documentation team's lead here, but some general guidance on what I'll need pre-approval for would be nice, especially when it comes to editing pages that other people maintain. I don't want to step on any toes, but also want to avoid bottlenecking the process with unnecessary overhead.
#61097 was marked as duplicate of this issue
Changed status from 'Needs Triage' to: 'Confirmed'
Added subscriber: @ThatAsherGuy
Added subscribers: @brecht, @nBurn
Added subscribers: @dfelinto, @Blendify
Considering you made this document are you willing to work on this?
For structure, my vote is to choose the second option
/Source/Design
My advice for even farther organization is to group resources by there module
My vote is to move the documents and add notes to them, it is then up to module owners to update the pages.
I am gonna leave these changes to the ultimate opinion of @dfelinto
@Blendify Yep, I'll do the work. It'd be rude of me to punt this late in the game.
Design documents go undo
Source/SomeModule/DesignDocument
. Please don't create separate places for design and code documentation, they should be together.In the past we've had too many top level categories and tags and other things that made it hard to understand the structure of the wiki and find things. Instead if you want to know about User Interface or Cycles related topics, you should just go to a page for that module, and find all the relevant documents on one page. Only if such pages become very long should we consider splitting things up.
Added subscriber: @EAW
Changed status from 'Confirmed' to: 'Resolved'