Page MenuHome

Wiki: Migrating and Integrating Design Documentation
Confirmed, NormalPublicDESIGN

Description

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:

  1. Edit the references so readers understand they're accessing historical content
  2. Migrate the documents to the active wiki
  3. Create new documentation
  4. 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:

  1. Adding a root /Design section for design documents
  2. Adding a /Source/Design sub-section for design documents
  3. 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.

Event Timeline

Asher (ThatAsherGuy) changed the task status from Needs Triage to Confirmed.Mon, Jan 20, 8:15 PM
Asher (ThatAsherGuy) created this task.

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 @Dalai Felinto (dfelinto)

@Aaron Carlisle (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.