Page MenuHome

Content Structure for the Developer Wiki
Open, NormalPublic

Description

Here's my proposal to update the organization of the developer wiki.
The goals are to:

  1. Improve on-boarding of new contributors.
  2. Serve as a reference for existing ones (including quickly finding links to share).
  3. Be a quick launchpad for frequent activities of existing programmers (eg. write release notes)

Overview of all content
Pages are grouped by topic (subjectively done by me :).
Some pages are not existing yet.
Some of the new pages are meant to aggregate content that is currently together with other topics. (eg. Communication and Style Guide for Commit Messages).
Some existing pages were discarded (Glossary, User Reference Manual, Supported_platforms).

Landing Page
Mockup for the links in the main page.
This is meant to be presented in cards with a short description and maybe some direct links to popular pages.

Plan for Renames and Broken Links
With all the content shuffling there will be some broken links.
For pages that get renamed -> Redirect.
For pages that get split or included in others (Commit_Access, Contact) -> Page done manually saying "The content of this page was moved to <link> and <link>."
For pages that don't get copied from the old wiki to the new wiki (glossary, etc) -> Page saying "The content of this page is no longer up to date. See it in the <link>archive</link>.".

Details

Type
Design

Related Objects

Event Timeline

Inês Almeida (brita_) triaged this task as Normal priority.

I don't fully understand the structure because a bunch of the blue boxes in the graph are not on the landing page. But generally this all seems fine and an improvement on what we have.

For pages that get renamed -> Redirect.

Right, the redirect is automatically created when moving pages in the wiki.

For pages that get split or included in others (Commit_Access, Contact) -> Page done manually saying "The content of this page was moved to <link> and <link>."

In most (or all) cases I think you can just redirect to the most similar page. For example Contact can just redirect to Communication.

For pages that don't get copied from the old wiki to the new wiki (glossary, etc) -> Page saying "The content of this page is no longer up to date. See it in the <link>archive</link>.".

Seems fine.

Landing Page Card Blue Box
New Developer IntroductionNew Developer
Building BlenderBuilding Blender
ToolsTools (IDEs, Debugging, Profiling, Blender Tools, Buildbot, Git, SVN, Arcanist)
GSoCGSoC
CommunicationCommunication
Module OwnersModule Owners, Roadmap, Git Statistics
ProcessProcess, Code Reviews, Testing, Bug Reports & Feedback
PythonPython
Source Code ArchitectureDesign and Architecture
Style GuideStyle Guide
Release NotesRelease Notes
TranslationTranslation
FAQFAQ, AMA (Ask Us Anything), Anti-Features
InfrastructureInfrastructure, Dependencies

"Bug Reports & Feedback"
I think that instructions/videos on how to do a bug report should be on phabricator, along with links for the channels where to pud feedback and feature requests. Maybe this could be improved before the beta?
However, the wiki could have an overview of what channels to check for feedback. It can also have guides on how to approach a bug report.

"Module Owners", "Roadmap" and "Git Statistics"
The idea of this section for me is to have a clear directory of who is working on what and when.
I still don't have a clear plan on how to present this and how to make it as automated as possible.

"FAQ"
I would like to reduce this as much as possible and simply point people to places where to get the information, instead of repeating it.
For example, both FAQ and Anti-Features have "Can I have scripting in other languages than Python". This should be documented in the Source Code Docs about the scripting API.

"Source Code Architecture" aka "Code Documentation"
We should agree on the name for this :)

This is great, anything to make it easier for people to download the source code, build and develop Blender is a big win.

Two things I don't see mentioned are the Blender Manual and UI/UX guidelines.

One last thing I'd like to mention is the issue of different compilers. Often a developer will only have access to a single environment. A recent patch of mine using MSVS broke compilation on Linux for instance. A cross-platform gotcha page would be helpful.

Thanks for the extra details.

Infrastructure: Infrastructure, Dependencies

What is dependencies in this context? If it's external libraries, that is part of Building Blender.

Module Owners: Module Owners, Roadmap, Git Statistics

If we maintain an up to date roadmap, then it really deserves to be a top level thing. We don't at the moment though.

If anything I would consider Module Owners more of a Communication subtopic.

I think that instructions/videos on how to do a bug report should be on phabricator, along with links for the channels where to pud feedback and feature requests. Maybe this could be improved before the beta?

We have a text on Phabricator with that information, which we can easily edit:
https://developer.blender.org/maniphest/task/edit/form/1/

Note however that we have already tweaked this text many times over the years, I would not change it lightly.

"Source Code Architecture" aka "Code Documentation"

I think Code Documentation is the better one.

@Brecht Van Lommel (brecht)

What is dependencies in this context? If it's external libraries, that is part of Building Blender.

Eeh... I don't remember! Such a clear plan... :X
It wasn't the subpage in Building Blender or https://developer.blender.org/diffusion/B/browse/master/build_files/build_environment/cmake/versions.cmake
I think the file taken directly from the source is a great idea. It's also possible to check out different revisions of that file to build older version of Blender.
I'll either remember what it was or leave it out :)

If we maintain an up to date roadmap, then it really deserves to be a top level thing. We don't at the moment though.
If anything I would consider Module Owners more of a Communication subtopic.

Agreed. I'll come up with a proposal for it, but if it ends up being just a list of people, it would go better under Communication.


Documentation on how to do bug reports:
On phab, I think that the form to enter a bug can be simplified further. (saying the same thing with less words)
That text links to these tips about bug reports, which is on the developer wiki. Can it be somewhere in phab, since it is for users?
Maybe @Pablo Vazquez (pablovazquez) could do a video on how to do bug reports? ^^

The phab landing page could also use some tweaks. Right now it's not so easy to report a bug for 2.8.
The default dashboard for users could do without the "Projects" and "Recent Tasks".


@Charlie Jolly (charlie)
^^
The Blender Manual is not a part of the wiki anymore. It's on https://docs.blender.org/manual/
"UI/UX guidelines" is a very good point. There is UI Paradigms, but maybe this could be moved under "Style Guide" along with some rules for wording of UI Elements.

Here is a proposal for the new design of the wiki, which is already available on wiki.blender.org (not enabled by default).

It provides:

  • navigation top bar with essential user links and page editing tools
  • sidebar on the left with fixed high level navigation (customizable in the Mediawiki:Sidebar space)
  • main content
  • sidebar on the right containing the TOC, displayed only over a certain window width
  • footer with licensing info and less-used utilities
  • responsive on mobile

This theme is based on the official Bootstrap documentation, it uses Bootstrap 4 and does not differ too much in functionality from the ancient Naiad skin that was used in the previous wiki.

Currently some of the "backend" pages need a bit more work, but I encourage anyone interested to enable the skin in their preferences.

After receiving some feedback, I would like to propose to adopt this skin as new default.

It looks great!

Thanks. I addressed all the suggestions, except for the logo. I already placed an updated version of the logo on the server, but it breaks with the default skin (too high res). I'll replace it as soon as we switch. The next steps for me are:

  • Create a card template (like the one shown in the previous attachment)
  • Create a page that will later replace the Main Page, and place the cards there

After that, if everyone is happy, we could switch skin.

Thanks, two more issues I noticed, on this page for example: https://wiki.blender.org/wiki/Reference/Release_Notes/2.80/Python_API/Addons

  • Note enough space after bullet lists
  • Missing box for code in <pre> tags, which is used like <source>.

Also I don't want to be too nitpicky, but the difference between <h2> and <h3>, and <h4> and <h5> is barely visible on that page. So the structure isn't very clear.

Thanks for the suggestions! I addressed them and deployed them.

You can find a preliminary version of the homepage in my user space.
Will work with @Inês Almeida (brita_) to define it further and then we can review it here.

Hello everyone,

I'm happy to volunteer for Wiki Web Development. Any guide for getting started would be very appreciated.

Thank you.

Hi Aditia, I started documenting our MediaWiki setup. I don't think there is much development to be done at this moment, but if you were able to check out my setup instructions and provide feedback that would be nice.

Ideally, anyone should be able to replicate our MediaWiki configuration.

@Francesco Siddi (fsiddi) Just checking in. I'm new to this mediawiki and your instruction is quite straight forward. Anyway how do I replicate content on my local docker environment?

You copy paste content from the existing wiki. Let's not derail this topic further, if you have any specific question feel free to reach out directly :)