launchpad development|
Size: 12334
Comment:
|
← Revision 26 as of 2011-06-21 14:53:00 ⇥
Size: 8831
Comment: Big edit of the LEP, eliminating unfruitful "discussion", moving implementation notes to a separate section
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 8: | Line 8: |
| '''As a ''' developer of an open source software project<<BR>> '''I want ''' a wiki<<BR>> '''so that ''' I can provide documentation to my users and plan my features more easily.<<BR>> |
|
| Line 14: | Line 10: |
| 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. | |
| Line 16: | Line 11: |
| What is the cause of this incompleteness? Try doing the following using '''only''' Launchpad: | Almost every open source software project needs somewhere to publish hypertext on the web. This might be for end-user system documentation, for storing notes about how developers do things, for planning out features or for things as yet undreamt of by man or woman. Case in point, this document. |
| Line 18: | Line 13: |
| * 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. |
When people set about starting an open source software project, or consider moving one to Launchpad, they need some place to publish this hypertext. Launchpad currently does ''not'' provide such a place, and this often makes people decide not to use Launchpad. |
| Line 23: | Line 15: |
| 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 [[https://blueprints.launchpad.net/launchpad|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 [[https://launchpad.net/silva/+announcement/7450|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. |
As such, the lack of wikis is an adoption blocker for Launchpad, particularly given that we fall behind our rivals here. Thus we should provide a wiki. |
| Line 31: | Line 19: |
| 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 * Lack of wiki space is an adoption blocker for newcomers to Launchpad who want an all-in-one project space |
|
| Line 46: | Line 27: |
| == User stories == '''As a ''' developer of an open source software project<<BR>> '''I want ''' a wiki<<BR>> '''so that ''' I can provide documentation to my users and plan my features more easily.<<BR>> |
|
| Line 50: | Line 37: |
| * Provide a wiki to each project | * Provide a wiki for each project |
| Line 58: | Line 45: |
| * Provide core page management features * Delete pages * Rename pages * Deprecate pages * Revert pages to previous version * See who changed a page and how * See who is alerted when you change a page |
|
| Line 61: | Line 55: |
| * Markup used on wiki should have same meaning in every chunk of user-entered text on Launchpad * Markup for easily linking to other elements of Launchpad (Use existing link parser that is used for bugs) * Allow users to subscribe to particular pages on wiki * Allow users to review and edit all of their wiki subscriptions * Lock down pages that are of particular importance or have become unusually controversial * Including images on wiki pages (png, jpg, svg) * Be able to link to pages on other wikis on Launchpad * Wikis for private projects must be private * Provide mechanisms for reporting abusive behaviour * Be obvious ''which'' project's wiki you are viewing / editing * Allow search * by title * for arbitrary page text * for pages that link to a specific * wiki page * bug * person * blueprint * branch |
|
| Line 64: | Line 77: |
| * Render Wiki pages from bazaar branches (Specify which branch to render pages from) | * Render Wiki pages from Bazaar branches (Specify which branch to render pages from) |
| Line 66: | Line 79: |
| * Page refreshless editing of wiki pages. * Markup for easily linking to other elements of Launchpad (Use existing link parser that is used for bugs) * Markup used on wiki should have same meaning in every chunk of user-entered text on Launchpad |
* Page refreshless editing of wiki pages |
| Line 70: | Line 81: |
| * Lock down pages that are of particular importance or have become unusually controversial * Be notified of changes to wiki pages |
* Printable versions of pages * Some kind of mass import system ==== Translation ==== * Way for translating pages from one language into another * Using Launchpad Translations to do this or help do this * Way to see progress for wiki translation for languages I am interested in * Way to see progress for wiki translation for all languages |
| Line 79: | Line 97: |
| == Subfeatures == | * Wikis for a project group – project groups are deprecated === Unsure === * Multiple wikis per project * Wikis for teams * They could just use the project wiki - That's like teams wanting their own bug tracker. * Some teams do want their own bug tracker, ''and'' teams already get their own space for branches -- jml [[<<Date(2011-05-26T12:21:53Z)>>]] * For what? If a team is building something, it's better to put it on the project wiki. Getting too fragmented here may be a problem, it may be better to just consolidate everything to the project wiki. * Wikis for distributions * Wikis for source packages * Ability to control who can view pages on a sub-wiki (e.g. per-page) basis * Ability to control who can edit pages on a sub-wiki (e.g. per-page) basis * Custom styling * No. Not a good idea at all; too many security holes here; risk of people using the display:none; property to hide stuff and mess up the page. Wikis are for information only; Launchpad isn't supposed to be pretty, just functional. * It works for blogger, wordpress, etc. Many people use wikis as their "shop front". A bigger concern is the usability impact of having something that looks completely different. -- jml [[<<Date(2011-06-21T14:53:00Z)>>]] |
| Line 83: | Line 116: |
| === How will we know when we are done? === When users can easily link questions and related bugs, make announcements without leaving Launchpad, create documentation in the time it takes to register for yet another external site, and use Bazaar to edit wiki files locally. |
|
| Line 89: | Line 118: |
| -- RobertCollins - some possible metrics: user adoption; change rate; Launchpad adopting it for its help and dev wikis. | * Can Launchpad itself adopt the wiki service for its help and dev wikis? * How many projects have non-trivial content on their wikis? * How much traffic do the wiki pages get? * Does the addition of wikis change the Launchpad project adoption rate? |
| Line 92: | Line 124: |
* May use [[http://launchpad.net/wikkid|wikkid]] for wiki engine. * -- 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. * -- Geoff - I posted that because the developer of that developed it in hope that he could get a wiki into launchpad; it meets all the requirements, and I don't see the point of recoding something that's already been done. * [[https://launchpad.net/wikkid|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 -- [[LaunchpadHome:thumper]] <<DateTime(2011-05-22T23:49:55Z)>> * -- RobertCollins - Why are these useful and desirable? It seems to be jumping straight into implementation and that concerns me. What's 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). * -- Geoff - Why use Launchpad's bug tracker instead of something like FogBugz? It's easier to set up, and already built in. * jml: Part of the answer is that a lack of wiki space is an adoption blocker for newcomers to Launchpad who want an all-in-one project space, so it's not critical that we produce something inherently better than competing standalone alternatives. * 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. * Some teams do want their own bug tracker, ''and'' teams already get their own space for branches -- jml [[<<Date(2011-05-26T12:21:53Z)>>]] * With source packages, we'll need to ask. Project groups are deprecated as far as I'm concerned. Distro is an interesting theoretical question, not sure it'll matter too much in practice. Source packages is an even more interesting question. Will try to find some folk from Ubuntu to talk to. -- jml [[<<Date(2011-05-26T12:21:53Z)>>]] * RobertCollins - Will the wikis need to link to each other? * Should be able to link to whatever pages you want. * Yes -- jml [[<<Date(2011-05-26T12:21:53Z)>>]] * Is one wiki enough? * XXX: ''A'' wiki? Launchpad itself has three wikis: developer, help and a Canonical-internal one * One wiki should be enough for each project. The Ubuntu wiki contains stuff from multiple projects, and has even been a substitute for this missing launchpad wiki. I don't agree with the way launchpad wiki is set up - they waste extra sub domains and space for no reason. * URL should be in the format of http://wiki.launchpad.net/project-name/Wiki_page * This has always been what I thought -- [[LaunchpadHome:thumper]] <<DateTime(2011-05-22T23:49:55Z)>> * I'd like to kill off subdomains entirely. -- jml [[@date@]] * Why? Please explain what you mean. -- xaav * Actually, I think we don't want to expose the Launchpad cookie to wiki content (for the same reason we don't expose the Launchpad cookie to librarian content or bzr branches). So that would suggest a separate domain and URLs like http://project-name.launchpadwikis.net/Wiki_page or http://launchpadwikis.net/project-name/Wiki_page -- [[LaunchpadHome:flacoste]] <<DateTime()>> * I don't think that that thats a necessary conclusion. At the LEP level 'be secure' is a requirement. On a implementation level we get to choose between allowing the wiki to render to arbitrary results or limiting what it can produce (so that we preserve the LP cookie). I think we should be guided by what we'd like in an ideal world in the first instance: the problems here are solvable. * I think the wiki should be formatted similarly to all of the other features (bugs, blueprints, code, translations). Users would still see their username in the top right corner, and all other features would apply. This shouldn't be an issue because the wiki will not contain any scripts (they will all be removed). * 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. * Inherit permissions from a Bazaar code branch * XXX: Why? This seems to be an implementation detail -- jml [[<<Date(2011-05-26T11:46:55Z)>>]] * This is the best way to handle permissions if we are going to be tracking pages using bazaar anyways. * XXX: Using bazaar isn't decided on yet, and even if it is, its not trivially obvious that using the branch permissions would be the entire answer. As jml says, this is an implementation detail, not a must-do or must-not-do. -- RobertCollins |
|
| Line 140: | Line 134: |
| * Ask the distro about their experiences with their wiki, unlikely to migrate to LP, but nice to know * Eventually it would be nice if everyone migrated to LP wiki; this isn't going to happen though. * Privacy * All pages should be public. LP may offer a deal where companies can pay for private wikis. * Migration? * People can just copy/paste their pages into launchpad wiki. This might be too big to undertake now; I would recommend placing this in a separate LEP after the initial one is completed. * Custom styling / CSS * No. Not a good idea at all; too many security holes here; risk of people using the display:none; property to hide stuff and mess up the page. Wikis are for information only; Launchpad isn't supposed to be pretty, just functional. * Search? * Of course. Don't see any problems with this. * Many wikis per project? * I was thinking only one wiki per project, http://wiki.launchpad.net/project-name. * Wiki pages may be layered, for example http://wiki.launchpad.net/project-name/Broad_topic/more_specific/small_section * Team wikis seem like a good idea * For what? If a team is building something, it's better to put it on the project wiki. Getting too fragmented here may be a problem, it may be better to just consolidate everything to the project wiki. * Attachments? * This '''may''' be a good idea, but you could just place pictures in the bazaar branches. Don't want to become a file hosting site with random people attaching their spare files to wikis. |
== Implementation notes == * URL should be in the format of http://wiki.launchpad.net/project-name/Wiki_page * This has always been what I thought -- [[LaunchpadHome:thumper]] <<DateTime(2011-05-22T23:49:55Z)>> * I'd like to kill off subdomains entirely. -- jml [[@date@]] * Why? Please explain what you mean. -- xaav * They force us to create useless pages (e.g. https://code.launchpad.net/), they encourage us to orient our content around our data model rather than what the user needs and they make use of Launchpad slower due to extra SSL negotations * Actually, I think we don't want to expose the Launchpad cookie to wiki content (for the same reason we don't expose the Launchpad cookie to librarian content or bzr branches). So that would suggest a separate domain and URLs like http://project-name.launchpadwikis.net/Wiki_page or http://launchpadwikis.net/project-name/Wiki_page -- [[LaunchpadHome:flacoste]] <<DateTime()>> * I don't think that that thats a necessary conclusion. At the LEP level 'be secure' is a requirement. On a implementation level we get to choose between allowing the wiki to render to arbitrary results or limiting what it can produce (so that we preserve the LP cookie). I think we should be guided by what we'd like in an ideal world in the first instance: the problems here are solvable. * Alternatively, the URL could be https://project-name.launchpad.net/ === Bazaar branch === * Inherit permissions from a Bazaar code branch * This is the best way to handle permissions if we are going to be tracking pages using bazaar anyways. * XXX: It's not trivially obvious that using the branch permissions would be the entire answer. -- RobertCollins * May use [[http://launchpad.net/wikkid|wikkid]] for wiki engine. * -- 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. * -- Geoff - I posted that because the developer of that developed it in hope that he could get a wiki into launchpad; it meets all the requirements, and I don't see the point of recoding something that's already been done. * [[https://launchpad.net/wikkid|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 -- [[LaunchpadHome:thumper]] <<DateTime(2011-05-22T23:49:55Z)>> * 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. |
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
Rationale
Almost every open source software project needs somewhere to publish hypertext on the web. This might be for end-user system documentation, for storing notes about how developers do things, for planning out features or for things as yet undreamt of by man or woman. Case in point, this document.
When people set about starting an open source software project, or consider moving one to Launchpad, they need some place to publish this hypertext. Launchpad currently does not provide such a place, and this often makes people decide not to use Launchpad.
As such, the lack of wikis is an adoption blocker for Launchpad, particularly given that we fall behind our rivals here. Thus we should provide a wiki.
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.
Stakeholders
This is a community driven project.
- Launchpad product strategist
- Launchpad technical architect
User stories
As a developer of an open source software project
I want a wiki
so that I can provide documentation to my users and plan my features more easily.
Constraints and Requirements
Must
- Provide a wiki for each project
- Either scale horizontally initially or have a feasible plan for such scaling
- Key points from the Ubuntu wiki / moin
- Page layout on disk
- Search
- Page subscriptions / mail
- Pages must be easily cached for anonymous users
- Key points from the Ubuntu wiki / moin
- Be free of single-points-of-failure
- Provide core page management features
- Delete pages
- Rename pages
- Deprecate pages
- Revert pages to previous version
- See who changed a page and how
- See who is alerted when you change a page
- Use a standard, existing markup language so that new users have less of a hurdle to learn Launchpad
- Be cleanly integrated with the rest of Launchpad (Blueprints, announcements, and bugs may all link to related wiki pages.)
- Be able to edit pages through the Launchpad web UI
- Markup used on wiki should have same meaning in every chunk of user-entered text on Launchpad
- Markup for easily linking to other elements of Launchpad (Use existing link parser that is used for bugs)
- Allow users to subscribe to particular pages on wiki
- Allow users to review and edit all of their wiki subscriptions
- Lock down pages that are of particular importance or have become unusually controversial
- Including images on wiki pages (png, jpg, svg)
- Be able to link to pages on other wikis on Launchpad
- Wikis for private projects must be private
- Provide mechanisms for reporting abusive behaviour
Be obvious which project's wiki you are viewing / editing
- Allow search
- by title
- for arbitrary page text
- for pages that link to a specific
- wiki page
- bug
- person
- blueprint
- branch
Nice to have
- Render Wiki pages from Bazaar branches (Specify which branch to render pages from)
- A WYSIWYG editor for wiki pages
- Page refreshless editing of wiki pages
- A way to branch the wiki, hack locally, and merge the wiki back to Launchpad's version.
- Printable versions of pages
- Some kind of mass import system
Translation
- Way for translating pages from one language into another
- Using Launchpad Translations to do this or help do this
- Way to see progress for wiki translation for languages I am interested in
- Way to see progress for wiki translation for all languages
Must not
- Require shell access for performing administration
Out of scope
- Wikis for a project group – project groups are deprecated
Unsure
- Multiple wikis per project
- Wikis for teams
- They could just use the project wiki - That's like teams wanting their own bug tracker.
Some teams do want their own bug tracker, and teams already get their own space for branches -- jml <<Date(2011-05-26T12:21:53Z)>>
- For what? If a team is building something, it's better to put it on the project wiki. Getting too fragmented here may be a problem, it may be better to just consolidate everything to the project wiki.
- They could just use the project wiki - That's like teams wanting their own bug tracker.
- Wikis for distributions
- Wikis for source packages
- Ability to control who can view pages on a sub-wiki (e.g. per-page) basis
- Ability to control who can edit pages on a sub-wiki (e.g. per-page) basis
- Custom styling
- No. Not a good idea at all; too many security holes here; risk of people using the display:none; property to hide stuff and mess up the page. Wikis are for information only; Launchpad isn't supposed to be pretty, just functional.
It works for blogger, wordpress, etc. Many people use wikis as their "shop front". A bigger concern is the usability impact of having something that looks completely different. -- jml <<Date(2011-06-21T14:53:00Z)>>
- No. Not a good idea at all; too many security holes here; risk of people using the display:none; property to hide stuff and mess up the page. Wikis are for information only; Launchpad isn't supposed to be pretty, just functional.
Success
How will we measure how well we have done?
- Can Launchpad itself adopt the wiki service for its help and dev wikis?
- How many projects have non-trivial content on their wikis?
- How much traffic do the wiki pages get?
- Does the addition of wikis change the Launchpad project adoption rate?
Thoughts?
- jml is very, very keen to avoid repeating the mistakes we made with Loggerhead:
- Inconsistent visual appearance
- Chronic performance problems due to scale mismatch
- Poor integration with the rest of Launchpad
- Navigation from loggerhead once you're there
- Extra clicks to get to code browsing
- Hard to re-use loggerhead elements in existing code pages
- Had to do extra work to integrate with Launchpad's authentication and authorization
Implementation notes
URL should be in the format of http://wiki.launchpad.net/project-name/Wiki_page
This has always been what I thought -- thumper 2011-05-22 23:49:55
I'd like to kill off subdomains entirely. -- jml @date@
- Why? Please explain what you mean. -- xaav
They force us to create useless pages (e.g. https://code.launchpad.net/), they encourage us to orient our content around our data model rather than what the user needs and they make use of Launchpad slower due to extra SSL negotations
- Why? Please explain what you mean. -- xaav
- Actually, I think we don't want to expose the Launchpad cookie to wiki content (for the same reason we don't expose the Launchpad
cookie to librarian content or bzr branches). So that would suggest a separate domain and URLs like http://project-name.launchpadwikis.net/Wiki_page or http://launchpadwikis.net/project-name/Wiki_page -- flacoste 2024-05-01 19:24:30
- I don't think that that thats a necessary conclusion. At the LEP level 'be secure' is a requirement. On a implementation level we get to choose between allowing the wiki to render to arbitrary results or limiting what it can produce (so that we preserve the LP cookie). I think we should be guided by what we'd like in an ideal world in the first instance: the problems here are solvable.
Alternatively, the URL could be https://project-name.launchpad.net/
Bazaar branch
- Inherit permissions from a Bazaar code branch
- This is the best way to handle permissions if we are going to be tracking pages using bazaar anyways.
XXX: It's not trivially obvious that using the branch permissions would be the entire answer. -- RobertCollins
- This is the best way to handle permissions if we are going to be tracking pages using bazaar anyways.
May use wikkid for wiki engine.
-- 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.
- -- Geoff - I posted that because the developer of that developed it in hope that he could get a wiki into launchpad; it meets all the requirements, and I don't see the point of recoding something that's already been done.
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
- 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.
