Jump to:
| Project: | Documentation |
| Component: | Other documentation issues |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (duplicate) |
Issue Summary
Hello all
Since you've decide to make this great work for a better Drupal documetation I want to offer an idea about multiple formats of documentation. For example you could look at django documentation (http://docs.djangoproject.com/en/dev/). I find it very cool.
First, it's centralized and consolidated in one place; second, it's well structured; third, and this is important, it comes in special text format — ReStructuredText (http://docs.djangoproject.com/en/dev/internals/documentation/) — which is simple txt files with special markup, so you can automatically convert it to any format like PDF, CHM and so on.
Django keeps their docs in SVN (http://code.djangoproject.com/browser/django/trunk/docs) — so versions and other issues are not a problem.
My personal opinion that django documentation is very useful — partly because of the structured and centralized infrastructure, and partly because of the doc formats. I can take their last version and convert it to CHM — for offline work — very useful! Maybe Drupal can learn something from this experience?
Comments
#1
This issue seems to have several parts:
1) Organization of doc... Django is a web programming framework (I think), so comparing the organization of the Handbook documentation on drupal.org to the organization of Django documentation is perhaps not the most useful comparison, as one is "how to use software" doc and the other is "how to program with an API" doc. We do have an API in Drupal, and that is documented on api.drupal.org; that site is fully generated from files checked into CVS. If you want to suggest specific improvements to how api.drupal.org is organized, please file them in project "Drupal", component "Documentation" (that is where all issues related to api.drupal.org belong).
We also all know the doc on drupal.org could be organized better... there are several open issues in the Documentation queue that address that. If you have additional specific suggestions about how the organization of doc on drupal.org can be improved, please feel free to file issues here under project Documentation / component Placement and Navigation.
There's also a major effort underway to improve many aspects of the drupal.org documentation, including its organization/information architecture and technology, which you can participate in: http://drupal.org/node/488070 -- there's a roadmap document available now, and an IRC meeting about 26 hours from now. Please join in!
2) Suggestion of putting drupal.org doc into source code control: I don't think we would actually want to put the Drupal handbooks (on drupal.org) into SVN or CVS. In my opinion, that would be too high of a barrier to participation, as the number of people able/willing to make SVN patches, review patches, and commit patches for documentation updates is much smaller than the number of people who are willing to click the Edit tab on a page and improve it. But the idea does have some merit, and probably should be considered. Again, the Major Doc Initiative mentioned above is looking at technology and how it can be used to facilitate making the documentation better, so you might want to get in on that discussion.
3) Suggestion of using some sort of generalized doc format like ReStructuredText, so it could be converted to different formats -- that is an interesting idea. It might be possible to do something like that on api.drupal.org, since that doc is generated from Doxygen; if you want to suggest that, the appropriate thing to do would be to file an issue with the API project (that is the Drupal module that is used to generate api.drupal.org). As far as doing that on drupal.org, which I think was the main point of your issue here, I'm not sure how it could be done (assuming we continue to edit the Handbook as Drupal book pages), but it's a good thing to keep in mind as we discuss technology in the major doc initiative mentioned above.
Since I think the concrete suggestions in this issue are related to technology of documentation, I am changing the component. Thanks for making your suggestions!
#2
I always wonder why someone would suggest using SVN and CVS to manage documentation. If Drupal can not be used to meet its own websites documentation, then what does this say about Drupal?
#4
Is this still an actionable issue? If not, can we close it as duplicate (to the existing initiatives)? (This is a perfect example of something that I think would be better discussed on the groups page if it wasn't read only - it doesn't really make sense as an issue, but it's the only way to post somewhere public...)
#5
Nothing to be done here. Marking as dupe