[drupal-docs] Round 4 of documentation sprint Admin help:merging into the handbook

[Charlie Lowe]

Definitely. It is hard to manage through email what is happening with 
these larger projects.

Two suggestions:

1) I've been suggesting, and I think it would help, if we would submit 
informal proposals for large projects. Something that is more than a 
list of tasks (such as round 4 of the documentation sprint). For example 
  a proposal along the lines of something like the following which could 
then be updated based on community discussion and serve as the project spec

* Objective and goals
* Document issues resolved by the project; how they are resolved
* Document issues relevant to the project but not solved by the project 
and why.
* To include a description of primary and secondary audiences for the 
documentation (might be shorter or longer depending on the project)
* Practical implemetation considerations (timeline, number of 
volunteers, technology restrictions, whether the project requires 
additional assistance from drupal-docs members or developers )
* Specific tasks of the project
* Requests for community involvement (an outline of what the project 
needs from the larger doc community, perhaps a prioritized list)
* Guidelines for writing the specific documents for the project (may 
refer to pre-existing guidelines)



2) Rather than the forum, we can already post initial project proposals 
to a project issue and post our comments there (gets mirrored to the 
list by email). Then the revised proposal as a project spec could be 
posted to the drupal-docs section of the "About the handbook" where it 
could be permanently maintained for future projects. Something like a 
project spec for admin/help could then be revised again for updating 
admin/help for Drupal 4.7. In other words, project specs could be 
dynamic documents.



Kobus Myburgh wrote:
> What I read makes a lot of sense, but keeping track of all the tasks as they are listed here on the mail becomes a bit tedious, and unmanageable, especially if you're out of the office as much as I am.
> 
> Maybe we should think of maintaining the core of the ideas that were discussed in one way or another? If you use, for example, a forum with restricted access, where you can have content threaded (good!) and filtered (as the forum topics are editable) (as opposed to non-threaded in your mail client, or only threaded and not filtered with mailing list archives) wouldn't it be easier to maintain?
> 
> The feasibility of this idea is highly into question, as I can't see a single person weeding out irrelevant information from the mails and posting them to the site, but, I would just like to hear some opinions and thoughts about this.
> 
> Regards,
> 
> Kobus
> 
> 
> 
> 
> 
>>>>cel4145 at cyberdash.com 5/24/2005 9:17:08 PM >>>
> 
> This sounds like the beginning of an interesting proposal. But let's 
> start by forming a documentation team (two people as coordinators) to 
> prepare a proposal for reorganizing/reworking that entire section. Right 
> now we have a proposal based on the viewpoint of one; one main goal of 
> the documentation teams is to present to the larger community a proposal 
> that represents the viewpoints of two people.
> 
> Meanwhile, at this moment, the goal of Kieran's project is to move the 
> admin/help into the handbook and make sure that non-empty pages exist 
> for the links in the admin/help which connect to the handbook. The 
> documentation team can then decide on the best method for organizing the 
> entire section at a later time and move this pages again if they see 
> fit. Otherwise, the alternative is not to go forward with the admin/help 
> integration for now until a documentation team can put together a 
> proposal for doing the entire section and we can discuss it.
> 
> However, Kieran is willing to manage the move as part of an effort to 
> get the admin/help submitted into Drupal core. This is his main priority 
> at the moment. Since Kieran is prepared to do this now, and no one was 
> forthcoming in forming a documentation team in the last few days for 
> restructuring this section of the handbook, I made a decision to let him 
> go forward with this project since he's committed and has people willing 
> to assist. I've been assisting as well and would invite everyone else to 
> join in.
> 
> So to reiterate, yes, these are interesting ideas. And two people 
> can/should form a documentation team to restructure this section of the 
> book. But at the moment, Kieran needs feedback based upon his goals. 
> Let's stay focused on the smaller picture now and save the bigger 
> picture for when we have at least two volunteers ready to move forward 
> with the larger project.
> 
> 
> 
> puregin wrote:
> 
>>     I'm a little concerned about making the Administrator's guide even
>>more confusing than it currently is.
>>
>>     I'm thinking of the new admin help as being similar in spirit
>>to Unix 'man pages', and I'm imagining collecting them all
>>into something which would essentially be an appendix -
>>used for reference.
>>
>>     I think that the existing content is sometimes of this format,
>>other times not.   I think that this existing content can be
>>coerced into more of a 'cookbook' format.
>>
>>    Here's the current structure: I'm going to associate chapter
>>numbers, to make discussion easier:
>>
>>    Administrator's guide
>>      1. Introduction
>>      2. Installation
>>      3. Configuration
>>      4. Blocks
>>      5. Drupal modules and features
>>      6. Upgrading from previous versions
>>      7. Migrating from other weblog software
>>      8. Backups
>>      9. Best practices
>>    10. Troubleshooting FAQ
>>
>>      I think of the Troubleshooting FAQ, Upgrading, and Migrating
>>sections as appendices, because they would likely be
>>read by only a subset of readers, and each of these sections
>>stands alone.
>>
>>      I'd like to see the Admin help become an appendix also.
>>Existing Admin help documentation could be put into a
>>'Versions prior to 4.6' section of this appendix.
>>
>>      I propose an organization something like this:
>>
>>    Administrator's guide
>>      1. Introduction
>>      2. Installation
>>      3. Configuration
>>      4. Day-to-day administration
>>           ...
>>           Backups (was 8.)
>>           ...
>>      5. Cookbook
>>           ...
>>           Best practices (was 9.)
>>           ...
>>    A1. Drupal modules quick-help
>>           Core
>>           Contrib
>>           Versions prior to 4.6
>>    A2. Upgrading from previous versions (was 6.)
>>    A3. Migrating from other weblog software (was 7.)
>>    A4. Troubleshooting FAQ (was 10.)
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>  
>>  
>>