Wiki: Migrating and Integrating Design Documentation #73275

New Issue

Asher · 2020-01-20T20:15:00+01:00

Asher commented

2020-01-20 20:15:00 +01:00

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:

Edit the references so readers understand they're accessing historical content
Migrate the documents to the active wiki
Create new documentation
Remove the references

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:

Adding a root /Design section for design documents
Adding a /Source/Design sub-section for design documents

Adding a `/Reference/Design` sub-section for design documents

The 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:

==== Warning: Archival Content ====
This page was copied from Blender's old wiki. It has been migrated here for the sake of convenience, as it's still referenced by the current team, but it isn't a live document. Some sections may not apply to the current version of Blender.

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.

This is the root design task for the work discussed [here](https://devtalk.blender.org/t/moving-design-documents-out-of-the-wiki-archive/10913/10) 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: - Edit the references so readers understand they're accessing historical content - Migrate the documents to the active wiki - Create new documentation - Remove the references This design task is going to explore the second option, using the [UI Paradigms](https:*archive.blender.org/wiki/index.php/Dev:2.5/Source/UI/UIParadigms) and [Tab Guidelines ](https:*archive.blender.org/wiki/index.php/Dev:Doc/Projects/UI/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: - Adding a root `/Design` section for design documents - Adding a `/Source/Design` sub-section for design documents # Adding a `/Reference/Design` sub-section for design documents The 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:](https://wiki.blender.org/wiki/User:ThatAsherGuy/UI_Paradigms) > ==== Warning: Archival Content ==== > This page was copied from Blender's old wiki. It has been migrated here for the sake of convenience, as it's still referenced by the current team, but it isn't a live document. Some sections may not apply to the current version of Blender. 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.

blender-admin commented

2020-01-20 20:15:00 +01:00

#61097 was marked as duplicate of this issue

Asher self-assigned this 2020-01-20 20:15:01 +01:00

Asher commented

2020-01-20 20:15:01 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'

Asher commented

2020-01-20 20:15:01 +01:00

Added subscriber: @ThatAsherGuy

Aaron Carlisle commented

2020-01-20 20:49:55 +01:00

Added subscribers: @brecht, @nBurn

Aaron Carlisle commented

2020-01-20 23:11:55 +01:00

Added subscribers: @dfelinto, @Blendify

Aaron Carlisle commented

2020-01-20 23:11:55 +01:00

Considering you made this document are you willing to work on this?

Structural Concerns

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

Contextual Concerns

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

Considering you made this document are you willing to work on this? > Structural Concerns 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 > Contextual Concerns 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

Asher commented

2020-01-21 01:18:43 +01:00

@Blendify Yep, I'll do the work. It'd be rude of me to punt this late in the game.

Brecht Van Lommel commented

2020-01-21 10:48:53 +01:00

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.

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.

Evan Wilson commented

2020-02-04 15:22:09 +01:00

Added subscriber: @EAW

Aaron Carlisle commented

2021-12-09 00:06:11 +01:00

Changed status from 'Confirmed' to: 'Resolved'

Aaron Carlisle closed this issue

2021-12-09 00:06:11 +01:00

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Wiki: Migrating and Integrating Design Documentation #73275

Structural Concerns

Adding a /Reference/Design sub-section for design documents

Contextual Concerns

Copy Editing Concerns

Process Concerns

Adding a `/Reference/Design` sub-section for design documents