Wiki

A wiki to provide documentation and feature planning for launchpad projects.

Contact: https://launchpad.net/~xaav/+contactuser
On Launchpad: https://bugs.launchpad.net/launchpad-project/+bugs?field.tag=wiki

As a Developer
I want a Wiki
so that Projects can provide documentation to their users and developers can plan features more easily.

Rationale

Launchpad is meant to offer a complete project solution with code, translations, bugs, a homepage, and feature tracking. Launchpad, in it's current state, is almost complete, but 'almost complete' means more user frustrations and complaints about missing features.

What is the cause of this incompleteness? Try doing the following using only Launchpad:

- Creating robust, collaboratively edited documentation. - Creating a full featured, formatted announcement. - Tracking features with robust, indexed, easy to find specification. - Hosting a static website that explains the project's goals.

The above tasks may be possible to do, but are difficult and confusing for users. Consider documentation: Documentation could be stored in blueprints, but formatting would not be present, making difficult for users to read. Also, the blueprints are not designed for storing documentation, they are primarily used for planning documentation. Blueprints may even link to an external website or wiki that contains further specification. Some projects, like this one, don't even use blueprints but instead use a wiki.

Creating a full featured announcement on Launchpad is not preferred. Many projects, like this one choose to link to an external site or wiki, primarily because Launchpad announcements are not designed to contain the fully body of an announcement, but only a teaser. Launchpad announcements contain no formatting, which is fine for their purpose, but this creates a need for external software.

Blueprints depend on an external wiki to track feature specification. They display only a summary of the specification, then link to an external source to display the full specification. Wikis provide a way to collaboratively edit the specification, and share it with others.

Hosting a website on launchpad creates problems with XSS attacks and other security issues. Creating a wiki would eliminate, or greatly reduce this need, because users could place their site content on the wiki.

This list represents only some key advantages to having a wiki; there are many more uses for wikis. Wikis are adaptable because you may fill them with anything you wish, providing collaboration for future projects. Hosting them on Launchpad gives several benefits:

- One site for everything - a BIG convenience for developers. - Use bazaar to update wiki pages - one location for everything. - Get started easily - Start creating your wiki right away! - Integrate with other services - Link to Bugs, Questions, and Blueprints

Stakeholders

This is a community driven project.

• Launchpad product strategist
• Launchpad technical architect

Constraints and Requirements

Must

• Provide a wiki to each project
• Either scale horizontally initially or have a feasible plan for such scaling
• Be free of single-points-of-failure
• Have no requirement for shell access to perform administration
• Inherit permissions from a Bazaar code branch

-- RobertCollins - I have rephrased the technical requirements to be assessable (millions of users isn't assessable without a lot of research into user patterns etc). I also removed the xss aspect as 'be secure' is a given -- RobertCollins - I wonder, will project groups, teams, users, distributions and perhaps even source packages want wikis? They could just use the project wiki - That's like teams wanting their own bug tracker. -- RobertCollins - Will the wikis need to link to each other? Should be able to link to whatever pages you want.

Nice to have

• Use markdown or equivalent instead of just filtered HTML.
• Render Wiki pages from bazaar branches (Specify which branch to render pages from)
• Be able to edit pages via Web UI. (WMD Editor - Possible?)
• Page refreshless editing of wiki pages.
• Could create custom URL's to link to questions/bugs/blueprints (Example Link lp:q:3333 - Question 3333)

-- Why are these useful and desirable? It seems to be jumping straight into implementation and that concerns me. Whats the audience of users? What do they want the wiki to do - why would they choose it rather than some competing thing (like e.g. publishing a sphinx doc site on packages.python.org).

Must not

-- RobertCollins - the render limit is already set sitewide for LP - 99% of page renders must be under 1 second (including any cold cache effect), all pages must be under 5 seconds or a timeout will occur. Existing work doesn't completely meet this but we are enforcing it on new works.

Out of scope

Subfeatures

Will use https://launchpad.net/wikkid

-- RobertCollins - why? wikkid is cool but I don't see how we can say its the right choice until we understand why we're doing this. And I don't understand that yet.

Success

How will we know when we are done?

When a collaborative wiki is implemented that provides an easy way to communicate information.

-- RobertCollins - This seems like we're done already - just use a non-LP wiki. Lets make it more focused on things that users will be able to do that they cannot do today?

How will we measure how well we have done?

-- RobertCollins - some possible metrics: user adoption; change rate; Launchpad adopting it for its help and dev wikis?

Thoughts?

URL should be http://wiki.launchpad.net/project-name/Wiki_page

• - This has always been what I thought -- thumper 2011-05-22 23:49:55

We should blacklist the "wiki" name as a series name, to allow the definition of lp:project/wiki to refer to the wiki for a project.

There should be a way to branch the wiki, hack locally, and merge the wiki back to Launchpad's version.

Wikkid was designed from the start to do this. As the primary developer and maintainer of wikkid, I'd love to see it used in Launchpad as it was the initial impetus to get it going -- thumper 2011-05-22 23:49:55