Confirming that no one else is working on Guide Documentation, Chapter 3

[Derek Atkins]

Tom Bullock <tbullock at nd.edu> writes:

> On 7/23/2010 5:47 PM, Tommy Trussell wrote:
>> On Fri, Jul 23, 2010 at 2:49 PM, Tom Bullock<tbullock at nd.edu>  wrote:
>>>   Is anyone else working on Chapter 3?  If so, I would like to coordinate
>>> with that person.  If not, can you all tell me to proceed with sending in a
>>> patch?
>>>
>>> Assuming you did tell me to proceed, another question.  When making changes
>>> to the documentation, what is the method to let all translators know so that
>>> they can add the changes to their "to-do" list for their language versions
>>> of the documentation?
>> I am not working on that section
> Should I infer you are working on another part of the documentation?
>> and I don't know the "official
>> answers,"
> Answers from whom can be taken as "official"?  a number of developers
> have stated they are currently on vacation.

I do not believe anyone is actively working on documentation.  I think
at this point you have announced your intention to work on documentation
(thank you!!!!) so just send email updates periodically (like, weekly?)
on your status.  Or better yet, send in the documentation updates
frequently, too.

>>   I
>> also discovered that in 2006 someone used the wiki to present/edit the
>> parts of the Concept Guide (and presumably started the page above,
>> too). See http://wiki.gnucash.org/wiki/Concept_Guide_draft/Overview
>> and the other linked text.
>>
>> The wiki might be a convenient way to get revision suggestions and
>> feedback,
>
> I think your suggestion is appropriate.  There should be a place and
> method to funnel all input and the statement of problems needs to stay
> separated from the documentation that explains the use of the system,
> at the very minimum to avoid confusion and support clarity.

At one point someone wanted to try to use the wiki for document editing,
but there's not a good way to take the wiki pages and turn it into
"real" documentation.  So that project sort-of died.

>> especially if you use an automated tool to convert the
>> sources between Docbook and wiki. I gather there are several
>
> I do appreciate your ideas and could use the help of your naming these
> automated tools that convert sources between DocBook and wiki.  Once
> having the name I expect to be able to google their sites and learn
> more.

That's the problem -- there are not really good tools to do
bi-directional conversion.

>> but I
>> can't immediately tell which were used in 2006... and depending on the
>> scripts the diffs back to the existing docbook source might be a
>> nightmare.
>
> Makes sense.  I think we should start with the present state and
> condition of the documentation and move forward as more becomes known
> about what works and what could be expanded upon.  Most of that
> learning would be mine or any that join in the effort until a current
> statement of present needs is made.  Such a statement would of course
> need to be submitted to the developers for their reflection and
> amendment.

I believe the actual docbook docs are canonical (except for the FAQ).

> Tom

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available