Bugzilla – Full Text Bug Listing
| Summary: | need to be able to version articles | ||
|---|---|---|---|
| Product: | Community | Reporter: | Rodrigo Peretti <rodrigo> |
| Component: | Articles | Assignee: | community.articles-inbox <community.articles-inbox> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | enhancement | ||
| Priority: | P3 | CC: | lmandel, wayne.beaton |
| Version: | unspecified | ||
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Windows XP | ||
| Whiteboard: | |||
|
Description
Rodrigo Peretti
How about we start requiring that authors specify the Eclipse projects and versions that they're referencing at the top of their article.? In the same space, we can provide links to previous versions of the article (with some indication of the related Eclipse project versions). We probably need to start treating these articles more like code. We don't tend to accept significant code contributions unless we have some plan for long term support, or retirement. We should do the same for articles. (In reply to comment #1) > How about we start requiring that authors specify the Eclipse projects and > versions that they're referencing at the top of their article.? > > In the same space, we can provide links to previous versions of the article > (with some indication of the related Eclipse project versions). That sounds good. > > We probably need to start treating these articles more like code. We don't tend > to accept significant code contributions unless we have some plan for long term > support, or retirement. We should do the same for articles. > Treating articles like code is a good idea (in terms of versioning, review, etc...) but asking authors for a long term commitment might impact the amount of articles written. I agree with Rodrigo. Writing an article is usually a one off effort. As an author I'm usually willing to make corrections and provide clarifications for readers but being responsible for updating the article with every release changes the commitment and is inconsistent with other publications. This type of change would really transform articles into official documentation - and it's hard enough to get the devs to update the documentation every release. I do think versioning is a good idea. Perhaps also allowing end users to view/search articles for a specific release. Note that I suggested that we needed a plan, not specifically a long term commitment from the author. I (in an uncharacteristic move) carefully selected my words. I've been striving to make articles have a very long shelf life, and--in general---I think we're doing a good job of that. Currently, I spend very little time thinking about retiring articles; maybe I need to spend more time. The plan might include adding some additional guidelines, like rejecting articles that use non-public APIs, requiring (as suggested before) that articles explicitly indicate the version of the project they're concerned with, and maybe coming up with a mechanism for filtering/flagging older articles. Wayne, that all sounds good except for retiring articles. I think many articles still have value even if they're out of date Eclipse version wise. Some projects and products are slow to adopt new versions of Eclipse and I think still find value in the older articles. (I like your idea of linking to old versions of articles from new versions.) I agree with Lawrence on not retiring articles. I've made a modest start on this. I've created a new CSS with entries for marking version information. I've added a notice to one article known to be out of date along the lines of: <div class="version-info"> <p><em>This article applies to Eclipse 2.0.</em> The contents may not be valid for other versions of Eclipse. <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=138906">Bug 138906</a> has been opened to discuss this article.</p> </div> This is not a complete or optimal solution. This first step is an attempt to figure out how to present the information to the user. Ideally, I'd like to capture (possibly in an XML file or something) some meta data about the projects and version ranges an article applies to, along with numbers of bugs concerned with the article. I think we may be able to use the project info database in conjunction with meta data about the article to figure out dynamically when an article is out of date. I've implemented a scheme that lists the project and release numbers for articles; the information is represented in XML in a file in the article's directory and is dynamically parsed and presented when the article is requested. This only works on articles that use the "new" format. There's an example here: http://www.eclipse.org/articles/article.php?file=Article-CustomDrawingTableAndTreeItems/index.html Note that I've been converting more articles to the new format. While I believe it will take some time to get them all converted, I should make some excellent headway. The XML file format is pretty simple. I haven't created a schema for it. You can take a look at an example here: http://www.eclipse.org/articles/Article-CustomDrawingTableAndTreeItems/info.xml As I said, the format is pretty simple. You can provide zero or more "bug" elements: one for each bug concerned with the article. You can have zero or more "project" elements. The "id" attribute contains the id of the project in the foundation database (the same value used for the project summary pages); the id is mapped to the name of the project when it is rendered. You can provide zero or more "release" elements, each providing the version number of a release of the containing project. At some point, there may be some need to be able to search for articles based on this information. At that point, we may need to consider moving this information into the database. For the time-being, I believe that this solution is good enough. I have the link currently pointing to the project's summary page. Should it point elsewhere? Should I include additional links? Should the links open a new tab/window? Comments welcomed. I'm closing this bug as FIXED. Reopen if you disagree with me. |