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

[Charlie Lowe]

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.