This page is part of the ongoing DocumentationDiscussion
What is already available, what is not, how can it be used/organized/formatted. Plus bending RDoc to our will.
WikiGardening required. This document was (roughtly) cut out of DocumentationDiscussion and could use a good scrubbing down.
What PHP Documentation does well
- good overall breakdown:
- Getting Started, Installation and Configuration, Language Reference, Security, Features, Function Reference, .. API .., FAQ: Frequently Asked Questions, Appendixes
- there is a mix of subject specific material (features, security, installation), broad general information (getting started, language reference) and very specific (function ref. and APIs)
- it is important to cover the very granular and the big-picture. Seasoned users will likely spend most of their time in the API reference, but new users need context, guidance, introductions.
Beefs with RDoc
- contains only API details, not “manual style” content. Doesn’t stitch the pieces together, just enumerates all the different parts. This creates challenges for new users, since they don’t know where to begin. We need some content that relates to generic concepts (like sessions for example) that explain how they work in Rails and points to the API references. Many of the READMEs contain this sort of info, but are too brief to be the last word on the matter.
- allow user comments
Further, I think we have to determine what information is needed from rdoc, and how to go about getting it…
User Interfaces: Encouraging (the right kind of) Interactions
User Contributions
PHP.net’s comments are at times more useful than the docs proper. We need to look at
- what shape these user contributions have (comments? wiki? threaded?
- What about if each page has the official docs, then a wiki content section, followed user comments/discussion at the bottom of the page.
- LeeO: I think having both wiki and user comments is a little redundant. Xal suggested exposing the rdoc code as editable through a wiki like interface(as well, he suggested that the changes could then be auto-submitted to the issue tracker, but xal is a little crazy!).
- how we can leverage exising resources (eg this wiki) and foster cross-referencing between the api docs & wiki / other resources where appropriate
- user accounts? how do we handle / foster cross-linking to & from the rails docs & wiki?
Content sources
- How is non-source documentation to be maintained? Should all documentation ultemately be rdoc in a source file somewhere?
- What are the relationships between the API docs, the wiki, manuals (other sources?) ?
- What are the sources of documentation:
- rdoc in source code
- readmes (and a few other non-code files)
- wiki
- manuals
Coralling the docs
I see two possible approaches for retrieving it from rdoc and into a db:
1. write or extend one of the rdoc generators.
2. have rdoc generate an xml file and parse that.
Rdoc generator:
Pros:
- can probably extend another generator
- less intermediaries (no middle step)
- better access to full set of raw info before cross-references are made, etc.
Cons:
- hacking another project (How easy to install?(Is that a valid issue?))
Parsing the XML document:
Pros:
- working with a document that is well organized and staightfoward to parse. (static file?— rdoc can stream the xml instead of saving it)
- It’s already been parsed. It’s very close to the structure and content we want.
Cons:
- all the links need to be corrected. They’re generated as for html(sequential #001 method ids, relative within each module)
Questions for developers/higher-ups
- Doc sources: Should rdoc be the primary/sole source of documentation? Does this include non-api documentation?
- Release: Revision name/version are to be manually entered. Is there another way?
- Previous versions: Is keeping back-versions important? That is, keeping documentation of previous releases?
- Multiple versions should be supported. For instance, when Rails 2.0 comes out there will additions and may be some (likely minimal) breakage. Since people will have different versions installed and not always be able to run the newest version, in the long term it needs to have this ability.
Formats
- Ability to import in some automated fashion
- RDoc xml?
- An extensible XML API that allows anyone to tap into the core information of the doc, and transform it to their liking
- Would allow others to tinker with the UI on their own machines.
- Would allow HTML & PDF Versions updated dynamically via XSLT
- single file PDF downloadable/printable version.
Idea Bin
There are some good ideas(which were lost in a recent rollback) that came up on IRC. See xal’s comments on around here http://www.loglibrary.com/show_page/view/62?EndTime=1112121192&StartTime=1112120852