Wiki reorganization

From Qubit Toolkit
Jump to: navigation, search


[edit] Proposal

Because one of the goals of this project is the participation of a distributed team of developers, the use of online tools like this wiki is important

Encouragingly, this wiki has already grown quickly and is a useful tool. However it's grown organically, and could be reorganized so that it's more useful to both new developers and deeply involved developers

[edit] Status

  • Created tools page, with inventory of all our project tools, and some instructions how to use them
  • Created Subversion page, for collecting information about using Subversion
  • Created development "main page", for details about contributing code to this project, configuring your development environment, and documentation on all development activities
  • Created project "main page", for information about this project's purpose, goals, and sponsors, and links to contributors, meetings, and tools
  • Updated Main Page with links to development and project sub pages

[edit] Naming conventions

Naming conventions for pages and categories

[edit] Categories

MediaWiki categories are used to help group and organize wiki pages with similar content - as well as creating pre-generated "link list" pages, e.g. Category:Development documentation

[edit] Namespaces

It's my impression that MediaWiki "namespaces" can be used to avoid naming collisions, like is install a page about development of the installer, or documentation for administrators on how to install the application?

I think that a difference between "namespaces" and categories is that a page may move from category to category as it evolves, whereas the namespace identifies the purpose of the page?

I think we might consider creating a "Development:" namespace, to break naming conflicts between regular documentation and development documentation

I think another candidate is "Testing:" to break conflicts between documentation of a feature and a description of tests for that feature

Not so sure about a "Meeting:" namespace... we don't have a problem with naming conflicts of meeting pages - but that's because we basically already use a namespace, all "meeting" pages are so named. Would there be any benefits to using an official MediaWiki "Meeting:" namespace?

[edit] Organization

Here's the list of all pages currently in this wiki

At the coarsest level, this wiki should currently break down into three sections,

  • Project - project meta information
  • Development - development information
  • User - user information

[edit] User

I think we can improve on the "user" section. I think it's not concrete what you expect to find in the "user" section. I think that explains why there's currently no "user" landing page

Currently we have the administrator manual and ica-atom:User manual in the "user" section - how about we instead create a documentation section? This would include links to all the documentation, as well as information like how to contribute documentation and any documentation style guides, etc.

I think another section that we're missing is support - I've seen "support" links on many other project pages - the idea is, visitors come wondering how they can get help. I think that because it's common for other sites to have a "support" section, using this pattern will make visitors comfortable because it's something they already know and expect

[edit] Project

The project main page provides information about this project's purpose, goals, and sponsors. It provides a list of the tools we use for online collaboration and project management, and a list of the people who have contributed to this project

[edit] Development

The development main page provides details about contributing code to this project, configuring your development environment, and documentation about all development activities

There's plenty of room to improve the style. Suggestions?

  • A colored list like the Main Page
  • Some general categories
  •  ???

[edit] Tools

The tools page is in the project section and is an inventory of our project management and online collaboration tools, with some instructions how to use them

[edit] Subversion

Information on how to actually use Subversion is spread across several pages. The Subversion page collects information which does not fit on any of the other pages, and links to each of the other pages which contain Subversion information

[edit] Style guides

Should these be reorganized? Merged or broken up?

Probably the editorial style guide should be separated from the coding standard, maybe a "main page" should link to each of these pages, or a category could be created?

Need to make a decision on what to call the landing page, currently leaning towards Category:Style guides

[edit] Navigation

I'd like to put some of the links from the main page, development page, etc. into a footer available on every page, similar to these examples,

[edit] Editorial style guide

Coding standard#Editorial style guide

[edit] Uses

There might be many different ways to organize the wiki, so we might give some thought to who uses the wiki and what makes for useful structure. For example, do we want it primarily organized around the features we are building, or the activities of wiki readers (looking for user/developer documentation)?

[edit] Current

What is this wiki currently used for?

  • Installation instructions
  • Project introduction
  • Code documentation
  • Contributor accreditation
  • Links and instructions for project tools like Subversion, issue tracker, etc.
  • Architecture documentation
  • Details on how to get support
  • Documentation on how to use the application, user manual
  •  ???

Peter: In my opinion our biggest challenge is finding the balance between the different uses for this website,

  • project homepage
  • documentation for new users
  • "in-flow" tool for developers to capture thoughts, discussion, decisions

[edit] Future

What could we additionally use the wiki for in future?

  • Download page - this belongs under the "User" section and may point to the ICA-AtoM project, or to the Subversion repository instructions?
  •  ???

One of the key uses of the wiki for me (Jack) would be for design documents or project proposals, which ideally evolve into code documentation. For example, a new feature like an audit log might start out as a design document in the wiki, enabling other project members to read and comment. It would also be something to point to during discussions. Then as development progresses, the page is ideally updated to reflect the status of the project. When complete, it serves as a reference for other developers in the future

This page itself (wiki reorganization) is a sort of "project proposal," intended to get discussion and feedback from other developers. So these "project proposals" may not always be on the subject of the code itself

Peter: The re-org that I am proposing here is based largely on my worry that we create a hodge-podge of pages sprinkled with inline discussion that make the wiki difficult to navigate and understand for new and existing developers alike

[edit] Examples

Here are some examples of mature project wikis which are usefully organized,

[edit] TODO

  • Next steps: I think our major task is to draft more complete code documentation and figure out how it relates to system architecture documentation and design principles (e.g. are they all the same thing or should they be split as I've done in this proposal)
  • Can we eventually merge the project about page into the Main Page?
  • Add tool (template? extension?) for better linking to Google project hosting issues and revisions. "commit XXX" pattern should auto link to Google project hosting, and display a summary of the change in the link title, like Google project hosting
  • Consider merging code documentation page and Category:Development documentation category?
    • Advantage: Create one page for all development documentation information and links, so linking to development documentation can be more consistent
    • Disadvantage: Do we ever want to link to just the documentation meta information (e.g. the guidelines) or just the alphabetical list? If we combine them in one page, we won't be able to link to them individually
  • Enable $wgUseTidy on all our wikis
  • Move the code audit documentation from contribute code to development main page. Go over the contribute code page again and possibly add coding standard, code audit, and testing information
  • Write some documentation for new developers, pointing them at useful resources like the symfony book, symfony forms book, Jobeet tutorial, others?
  • Create a support page
  • Create a documentation landing page

[edit] Notes

Could the page status be generated from category membership?

Personal tools