[drupal-docs] Idea - move help text out of code into database

[Anisa]

Alright, so we can all agree that a standard way of writing up various 
documentation would make it easier to write and easier to use. 

We can add to the style guide (which is generic to the whole handbook) 
for specific guidelines for specific kinds of documentation.  If you 
feel like expanding on the module guide I suggested, by all means.  :)

Anisa.
PS: On a beach in Okinawa until Tuesday.

Charlie Lowe wrote:

>puregin wrote:
>  
>
>>On 12 May 2005, at 11:34 PM, Charlie Lowe wrote:
>>
>>
>>    
>>
>>>I think whether or not the documentation is hardcoded or not is up to
>>>the development team. What we need to do is facilitates the process by
>>>which we can hand off to them the documentation that they need.
>>>They can then decide whether to handcode it or not.
>>>      
>>>
>>      I disagree that it's a development-team-only issue.
>>    
>>
>
>I think we disagree less than you think :)
>
>My point is that development has to decide what they want in terms of 
>admin/help documentation in terms of text. I'm not a coder. It's too 
>hard for me to read the documentation in the source code; it's too hard 
>to write.  In fact, it's the wrong way for anyone to be writing 
>documentation, IMHO. Almost anyone who finds it just as easy to write 
>documentation embedded in php instead of in plain text is probably going 
>to produce some pretty geekified documentation. LOL
>
>A couple of years ago, I began rewriting quite a bit of the modules and 
>features section. However, the process for submitting it was a mess from 
>a non-coder's standpoint. Some of it was pulled directly from the 
>admin/help php files, which meant submitting revisions into the handbook 
>involved getting it coded. That wasn't something I could do. Other 
>sections of the handbook were in the handbook, but that meant getting 
>them into the admin/help encoded once again. Plus, the only review 
>process was just to post the revision and wait for moderation. No 
>process in place for submitting a revision for feedback. Unlike code in 
>Drupal, documentation goes through very little discussion even when the 
>author is looking for discussion.
>
>There a push since then (maybe a year ago?) to revise the admin/help. 
>But it was done in code. The diff files that were offered for 
>documentation review were not something I could read and work with every 
>easily.
>
>So I had pretty much given up, and hoped that we would see more progress 
>  now that there are more people interested and involved. But right now, 
>I see the handbook development process still having lots of problems. We 
>have multiple potential versions going--handbook, handbook v2, and wiki. 
>We are doing document construction without documentation specs, 
>something extremely difficult to do in an open project like this because 
>it ends up being inconsistent. We have no clear review process in 
>place--and I don't mean formal. If a documentation team member has 
>developed a revision for the handbook that they feel is ready to post, 
>an improvement on existing documentation, I'm not thinking that there 
>needs to necessarily be a "formal" process. But what is the process for 
>submitting a revision for feedback? Seems like we have lots of choices 
>for the moment.
>
>So, yes, I believe that the admin/help should be part of the handbook 
>documentation. And I believe we have a lot to work on in developing the 
>handbook. But let's create specs with the developers based on creating 
>the documentation in the handbook and leave integration into the 
>code---however they want to do it--up to the developers. And let's focus 
>on creating a simple, smooth process for documentation construction. It 
>can be a lot easier than this.
>
>  
>
>>     I think you mean Anisa's post of Mar 29, 2005
>>
>>http://lists.drupal.org/archives/drupal-docs/2005-03/msg00309.html
>>
>>Seems like a good idea to have such a standard template
>>for help texts  and module documentation.
>>    
>>
>
>Thanks. And that's what I'm thinking of, only more refined and 
>developed. Clear documenation specs would make it much easier to write 
>good documentation. It makes it pretty formulaic that way.
>
>But not even just help texts. Even some general notes on writing other 
>sections. Boris just posted about Marketing documents. Those, too, could 
>use some minor specs to assist others in developing them.
>  
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050513/75c76181/attachment.htm